PC-SIG: Games

home *** CD-ROM | disk | FTP | other *** search

/ PC-SIG: Games / PC-SIG Games (PC-SIG).iso / 2581 / FIGMENT.DOC < prev next >

Wrap

Text File | 1992-09-17 | 338.2 KB | 8,468 lines

Figment The Imagination Processor User's Guide and Command Reference Revision 2.46 August, 1990 Copyright 1988-1990, Patch Panel Software 11590 Seminole Blvd. Seminole, FL 34648 813-397-3530 All Rights Reserved. Figment is a trademark of Patch Panel Software Information in this document is subject to change without notice and does not represent a commitment on the part of Patch Panel Software. The software described in this document is furnished as shareware. The software package may be re-distributed only in its entirety as the program "Figpkg.exe". Users are requested to register their copies. A more comprehensive, fully typeset and perfect-bound (paperback) version of this book is available to registered users along with upgrades. Additional graphics and music utilities are also available to registered customers. Consult the file "Order.frm" for details. Figment User's Guide Table of Contents Table of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1 A. Overview of Features . . . . . . . . . . . . . . . 1 B. How to Read This Document . . . . . . . . . . . . . 2 Part I. The Presentation Environment . . . . . . . . . . . 4 A. Getting Started . . . . . . . . . . . . . . . . . . 4 B. The Screen Display . . . . . . . . . . . . . . . . 6 C. The Object of the Story . . . . . . . . . . . . . . 7 D. Command Lines . . . . . . . . . . . . . . . . . . . 8 E. Synonyms . . . . . . . . . . . . . . . . . . . . . 11 F. The Actor . . . . . . . . . . . . . . . . . . . . . 11 G. Command Logs . . . . . . . . . . . . . . . . . . . 12 H. Command Reference . . . . . . . . . . . . . . . . . 14 Part II. The Story Editor . . . . . . . . . . . . . . . . . 28 A. Introduction to the Editor . . . . . . . . . . . . 28 B. Theory of Operation . . . . . . . . . . . . . . . . 28 C. How to Make an Interactive Story . . . . . . . . . 28 D. Method of Editing . . . . . . . . . . . . . . . . . 30 E. Cut, Paste, and Insert Functions . . . . . . . . . 32 F. The Top Level Editor . . . . . . . . . . . . . . . 34 G. Summary of Editing Operations . . . . . . . . . . . 35 H. Stuff Editor . . . . . . . . . . . . . . . . . . . 37 I. Scene Editor . . . . . . . . . . . . . . . . . . . 49 J. Story Maps . . . . . . . . . . . . . . . . . . . . 50 K. Story Rules (Logic Programming) . . . . . . . . . . 54 L. Editing Rule Bases . . . . . . . . . . . . . . . . 62 M. Pre-Command Rules . . . . . . . . . . . . . . . . . 74 N. Conditional Function Reference . . . . . . . . . . 77 O. Executional Function Reference . . . . . . . . . . 84 P. Player Maps . . . . . . . . . . . . . . . . . . . . 92 Q. Synonym Editing . . . . . . . . . . . . . . . . . . 93 R. Parameter Editing Screen . . . . . . . . . . . . . 94 S. Link and Attribute Type Definitions . . . . . . . . 98 T. Profiles . . . . . . . . . . . . . . . . . . . . . 99 U. Standard Messages and Text Variables . . . . . . . 101 V. Full-Screen Text Editor . . . . . . . . . . . . . . 104 W. File Management . . . . . . . . . . . . . . . . . . 105 X. Deleting Objects . . . . . . . . . . . . . . . . . 111 Y. Debugging Tips . . . . . . . . . . . . . . . . . . 112 Part III. Story Design . . . . . . . . . . . . . . . . . . . 114 A. Skill Level . . . . . . . . . . . . . . . . . . . . 114 B. Examine Strings . . . . . . . . . . . . . . . . . . 115 C. Health Points . . . . . . . . . . . . . . . . . . . 115 D. Strength . . . . . . . . . . . . . . . . . . . . . 116 E. Conflicts . . . . . . . . . . . . . . . . . . . . . 116 i Table of Contents Figment User's Guide F. Links . . . . . . . . . . . . . . . . . . . . . . . 118 G. Controlling the Random Number Generator . . . . . . 120 H. Potions and the Drink Function . . . . . . . . . . 121 I. Weighty Matters . . . . . . . . . . . . . . . . . . 121 J. Size and Containers . . . . . . . . . . . . . . . . 122 K. Waving the Flags . . . . . . . . . . . . . . . . . 122 L. Reading Scrolls . . . . . . . . . . . . . . . . . . 123 M. Strategic Weapons . . . . . . . . . . . . . . . . . 123 N. Food . . . . . . . . . . . . . . . . . . . . . . . 125 O. Characters as Containers . . . . . . . . . . . . . 126 P. Rules and Changing Scenes . . . . . . . . . . . . . 126 Q. User-definable Command Parser . . . . . . . . . . . 126 R. The Actor in Rules . . . . . . . . . . . . . . . . 130 S. The '@'-Words . . . . . . . . . . . . . . . . . . . 131 Index . . . . . . . . . . . . . 133 ii Figment User's Guide Introduction Introduction Figment is multi-media authoring system for interactive fiction. It is a tool for manipulating text (and when purchased, graphics and songs) under computer control either to present information or to create an illusion. This makes it good for developing certain types of simulators, role-playing trainers, and certainly for entertainment. Figment has special features for modeling character development which makes it a unique tool for character and plot modeling as well. You can develop stories and trade them with other Figment users. You can also obtain a copy of "Figlet", the play-only form of Figment. Figlet is the distribution vehicle for material you generate with Figment. Figlet users are licensed to distribute Figlet freely with their material to make stand-alone story disks. Figment is a spread-sheet/word processor/debugger for interactive fiction. You can write, play, and debug your work all in one package. No tedious compiling or loading is required. You can run your work immediately. Figment brings the logic out to the user level where you can modify it or do whatever you want with it. The editor displays all the data structures for you to modify. A. Overview of Features Briefly, Figment's many internal features are: 1. The window-managed display manages the screen efficiently during playback. Color is supported in text and graphics modes. 2. The Scene Description highlights changes during play in reverse video, an excellent aid to comprehension. 3. The command parser closely models natural English and supports series operators, multiple sentences, object synonyms, and function synonyms. 4. The user-definable command parser supports boolean operations on word groups. It makes possible a very flexible command entry and opens the story to include virtually any user statement as a legal command. 5. Function and object name synonyms. 6. Commands can be logged and played back like a player piano with speed control or single-stepped for debugging. 7. The system senses player efficiency and can respond with messages tailored to the user's skill. 8. Viewpoints allow you to describe situations from the point of view of the different characters in the scene. The player can assume the role of these characters to see the 1 Introduction Figment User's Guide story from their perspective and to manipulate the characters. 9. Full-screen data entry editors. 10. Text can be entered in a simple typing buffer or a full- screen text editor as required. 11. The at-symbol (@) denotes special words to be substituted into your text including the user's name, the Actor's name, the scene name, the command line, etc. 12. Cut and paste operations are supported for editing most data structures. 13. User-defined attributes let you build rich character definitions. 14. Character profiles present a weighted decision matrix of attributes so you can say for example "If Actor does not fit profile of leader..." 15. User-defined object types, a useful adjunct to profiles. 16. Links between objects can have user-definable types with positive or negative values. You can interpret the values as meaning like/dislike, strong/weak, attraction/ repulsion...whatever you like. 17. Frame-based inference engine. The rule-base is built in small rule-bases local to specific situations allowing good performance. Both global and local rule-bases are supported. 18. The Player map gives the player a memory of places and things, and fore-knowledge of them as well. It allows commands like "find object_name" or "go to place_name". 19. Script file output can be generated from your story. The script can be printed on your line printer or edited in your word processor. In addition, graphics and music can be keyed to the story for a multi-media presentation. The graphics can be displayed in a windowed text-with-graphics style like a WYSIWYG DTP package. This version will play music and graphics, but they cannot be written without the optional graphics and music library utilities. The music requires an Adlib board for playback. Contact Patch Panel for more information. B. How to Read This Document Figment has two distinct parts: the Presentation Environment, and the Editor. Part I of this book describes the Presentation Environment where you play the material that you have written. Part I closes with a reference guide of all the commands used in Playback mode. Part II discusses the Editor. This part describes only the mechanical process of editing the data. It deliberately 2 Figment User's Guide Introduction postpones discussion and theory to Part III. Part II includes a reference guide of all the conditional and executional functions you use to write your story rules. Part III describes the inter-relationship of all the pieces and illustrates constructions used to create different effects. Part III is organized by topics and represents the programer's notes for every feature. The Appendices discuss revisions and data conversion considerations when converting stories from older revisions. Note: Figment has an optional graphics presentation mode, but you will find no mention of it in this document. For information regarding any graphics operation, consult the User's Guide for the Figment Graphics Library Utility (Figglu) distributed with the Figglu software. Similarly, any discussion of music- related work is found in the corresponding book for Emilu. 3 Presentation Environment Figment User's Guide Part I. The Presentation Environment When you start Figment, you enter the presentation environment. Here you find a scenario description and you give English-like commands that act upon the various scene elements. Your software comes with a demo story, an accompanying log file, and a file called "super.clu" for people who haven't the time to struggle. A. Getting Started Stories are kept in files with ".sdf" file extension, but you do not specify the extension. All you have to do to start the demo story is type "Figment" followed by the path to the story data file: figment demo figment b:demo ;demo on drive b figment c:\datafiles\demo ;demo in another directory It's a good idea to do this now so you can follow along with the discussion. A title screen is displayed, and your story begins, but before we proceed, we should stop and describe other options for starting Figment while we are on the topic. 1. Starting a New Story When you want to write a new story, you simply make up a name and specify that when starting Figment. Thus: figment mystery creates a new database. Read the section on File Management in Part II. 2. DOS Command Line Switches Figment lets you specify different options using command line switches, indicated by a slash, when you start the program from DOS. You may place a switch anywhere in the DOS command line (except on the word "figment" itself) and Figment will find it. For example: Figment /s Figment /s demo 10 Figment demo/s 10 4 Figment User's Guide Presentation Environment Figment demo 10 /s All of Figment's switches can be combined and given in any order. You may use upper or lower case letters. Switches are removed from the command line before Figment counts its arguments. Thus: Figment /s demo 10 Figment sees "demo" as its first argument and reads the file called "demo.sdf". It sees "10" as its second argument, the seed specification for the random number generator. a. Suppress Status Indicator Switch - /s Some stories do not need the Status Indicator. This switch suppresses the Status Indicator display. b. Suppress Inventory Switch - /i This switch suppresses the inventory display. c. Select Display Switch - /Dn Figment automatically tests and selects the appropriate display mode, but some clone adapters (notably non-register-compatible EGA clones) can confuse the test giving undesirable results. The system appears to "hang". If this symptom occurs, try specifying the adapter manually with the display switch: figment demo 10/D3 ;3 = EGA Color /Dn where n= 1 MDA Monochrome Display Adapter (No graphics) 2 CGA 3 EGACOLOR 4 EGAMONO 5 VGAMONO 6 VGACOLOR 7 MCGACOLOR 8 MCGAMONO 9 HERCULES EGAMONO and VGAMONO tells Figment to use Black & White text even though the devices can model colors as shades of gray. Conversely, you could force mono screens to "color" when you want them to display gray text. 5 Presentation Environment Figment User's Guide Note: Forcing a non-Hercules device to Hercules mode might not be a good thing to do. B. The Screen Display Once you have started Figment, you should note four distinct regions on the screen. These regions are "dynamic", meaning they stretch and shrink as needed to accommodate changing needs. 1. Status Indicator The Status Indicator, printed in reverse video at the top of the screen, displays the status of a few key story parameters. It can be customized to the story requirements. Some stories might not use it at all. 2. Inventory The Inventory region grows as your list of acquisitions grows. Again, some stories might not use it. It changes when you change viewpoint to reflect the actor's possessions. (A useful feature since you might not know them otherwise.) 3. Scene Description As the story progresses, elements of the Scene Description change. The newly changed descriptions are displayed in reverse video to emphasize them making it easy to see the effects of your commands. The Description Window can process multi-page descriptions. The screen display pauses and you get the message "strike any key to continue" between pages. The Scene Description comes in long and brief forms. Shift between modes with the toggle command: >toggle Think of this as though there were a two-position toggle switch on the instrument panel. One position is labeled "Long Mode" and the other position is labeled "Brief Mode". Each time you give the "toggle" command you are switching the display from one mode to the other. You are said to be toggling the display. 6 Figment User's Guide Presentation Environment 4. Command Window The Command Window scrolls your commands and their responses. Figment displays its ready prompt, "Player:". If you entered your name at the start then it displays your name here, and it also changes names to reflect the name of the actor when you change viewpoints. The Command Window scrolls split-screen fashion as you give commands so that the scrolling lines do not destroy the Scene Description. Ordinary reports to your actions are given to the command region: >go east You can't go that way. The Command Window can also process multi-page responses, but note that the command dialogue is always sacrificed; it scrolls off the top of the Command Window and is lost. Therefore be sure you have read this message before typing any key to continue. C. The Object of the Story Most interactive fiction is driven by manipulating objects, meaning you can examine them, take them, drop them, etc. They represent "story variables". (Figment also recognizes special complex statements. See also the User-Defined Command Parser.) Some objects, function as containers which can hold many other objects. Opening these objects reveals their contents while closing them conceals the contents. Object names are composed of a few words, at least one of which should be embedded in the scene description so that you have a couple of chances of guessing right. Either of the words is a legal handle to identify the object. An object called "oil lamp" might be addressed in any of the following ways: >take oil >take the oil lamp >take the lamp lighting the room >take the lamp and jump in the lake Common modifiers like "a", "an", "the" etc. are ignored. The command processor gets the drift early in the command and ignores any elaborations you tack on the end. You may use upper or lower case letters as you like. By now, you should recognize that commands begin with verbs. 7 Presentation Environment Figment User's Guide Verbs cannot be abbreviated: >ta balloon I don't understand the command: "ta". >take balloon You take the Red Balloon. Object names represent arguments to the verb functions. Names can be abbreviated: >take ball You take the Red Balloon. This presumes that the string "ball" is unique within the current scene. If, however, there were an object called "Blue Ball" in the same scene, then you would be just as likely to get the Blue Ball as the Red Balloon. D. Command Lines Figment can tolerate commands longer than several lines. If your command should reach the end of the screen line, keep typing. The cursor will "wrap around" to the next line to continue echoing your typing. Finally, hit "Enter". Many punctuation operators are supported. Spaces before or after these operators are optional. It is best not to use punctuation except for cases as described here. Figment lets you make complex commands that are broken down into simpler commands for execution and logging. Thus the command: Take the bat, ball and glove from the box, and give them to the boy. would be broken into: take bat from box take ball from box take glove from box give bat to boy give ball to boy give glove to boy and dispatched for processing and logging. The resulting log appears as though each little command were given separately. Conversely, text files of commands can be read back into Figment as command logs. These text files can contain the complex commands since Figment will break them down into the simpler 8 Figment User's Guide Presentation Environment forms and dispatch accordingly. (See Command Logs.) 1. Articles Articles such as "the", "a" and "an" are stripped out. You need not use them if you do not want to. They look nice in documents like this so we use them in our examples. 2. Text Editor for Commands The full-screen text editor is implemented for the command buffer so that you can correct mistakes. Hit F6 anytime while typing to get the text editor. "Escape" exits the editor and leaves the cursor at the end of the newly edited command line waiting for you to hit Enter. 3. Multiple Sentences in a Command - the Period Operator Multiple sentences can be given in a single command separated by a period. Thus: Take the bat. Go north. Give the bat to the boy. Figment will stop executing at the first failed command (caused either by user-error or the author's inhibiting the command) and wait for a new command line. If you hit F6 immediately, you will get the failed command for editing. The last period on a line is optional. 4. Series Operations - the Comma Operator A comma between objects signifies a series of objects to be submitted to a command for repeat processing. A series may also use the modifier "and", and spaces are not required when the comma separates the objects. Note that a series can be as short as two objects: take bat,ball take bat and ball take bat, ball, glove. take bat, ball, and glove take bat, ball and glove take bat,ball,and glove A series may be embedded between the verb and its modifier: 9 Presentation Environment Figment User's Guide take bat,ball,glove from box give bat,ball,glove to boy but a series cannot be used with destinations after the modifier: take candy. give candy to Bobby, Billy and Mary A series cannot be used with verbs. "Take, drop and kick the football" is illegal. 5. Pronouns a. "it" Substitutes the last object used. If no previous definition for "it" exists, the message "vague pronoun reference" is issued. Take the book from the box and give it to the boy. Note that this will give the book to the boy and not the box to the boy. Note also that this carries over between commands: Take book. examine ;examines scene leaves pronoun unaffected Give it to the boy. This pronoun can lead to some confusion: Take the arrows and give it to the indian. Technically, this is correct since the object named "arrows" is a single object, but the name implies a plural case causing some people to say "them" which would substitute a series yielding unexpected results. b. "them" A pronoun that is used to substitute the last series used. Take the bat, ball, and box, and give them to the boy. This variable is also global between command lines and it also returns a message, "vague series reference", when no 10 Figment User's Guide Presentation Environment definition exists. E. Synonyms Figment supports synonyms for the command functions and for the object names as well. This makes the story more flexible and lets it flow smoother. The author defines the synonyms. "q" is the synonym for "quit". F. The Actor The Actor is the character speaking to Figment. Most often, this is the Player, but when you see a different character in the scene, you can assume that role and act as that character. When you begin a story, the command line indicates that the current Actor is the Player. It does this by printing a ready prompt that is the player name followed by a colon. It looks like this: Player: You change the Actor by typing the name of a character in the scene followed by a colon ":". Figment responds with a new ready prompt indicating the new character is speaking. Using an example from our demo: Player: fairy: ;the player becomes the fairy Toothy Fairy: ;and performs now as the fairy This action costs no moves and triggers no story logic. Of course the character must exist in the scene or you get an error. You also get an error message when you omit the colon (:). You can combine this action with the command for the actor: Player: fairy: examine wand <examination report of fairy's view of wand follows> Toothy Fairy: The fairy remains the Actor until you decide to change back to the player or to another character. When you change the Actor, the Status Indicator changes to reflect the new Actor's attributes. The Inventory also changes to reflect the Actor's possessions. The Scene Description changes to reflect the new Actor's viewpoint. This may change only a portion of the description depending on how much of the 11 Presentation Environment Figment User's Guide story is written from the new Actor's viewpoint. G. Command Logs Commands can be logged in a disk file for later replay. Mistakes are not logged. The replay can be automatic like a player piano or single-stepped by hitting the F9 key. Command logs are intended primarily so designers can debug their work, but other uses are emerging. They are useful for generating script files. They are 95% cheaper than save files for reproducing a previous state and they can reproduce every state along the way to the final one. You would need maybe a hundred save files to do that. An Interactive Fiction is a database of objects and rules for their behavior. The log file extracts a story from that database. You can change the log file and get a different story from the same database, hence a different script. The different logs represent different plots. If you are using Figment as a prototyping system, you can keep different logs to experiment with different story lines. The log playback can be interrupted and restarted so you can stop and study your data. You may play or step a log file to any point in the log. If you then turn logging on, your commands will be added from that point on, effectively changing the log to your new sequence. However, the best way to make command logs is to use your text editor. That way, you can put comments on the end of any line indicated with a prefixed ";" character. Thus a command sequence such as: take the ball ;the boy left it here north ;enter the house pause ;stop to check data in editor put ball on table ...commands continue like this can be written in a word processor and used as a log file. Comments must end before the end of the line. Of course a log file made in Figment cannot generate comments. The text file from your word processor must not contain any word processing codes such as margin settings, fonts, indents, page breaks etc. If the resulting text file will not type cleanly with the DOS "type" command, it will not be suitable input for Figment. Logs can be played back at user-defined speeds. The command: 12 Figment User's Guide Presentation Environment play demob 5 will play the log file called "demob.log" with a 5 second delay between commands. Users with high speed 386 processors will probably want to use this option to slow the playback down. The delay is specified in integer seconds. You cannot specify delays less than one second. You can specify any log file name you like. If you do not indicate a log file name, the system will use the last log name used. Failing that, it will use a log file with the same name as the story. See also the Command Reference for the "play", "log" and "step (F9)" commands. 13 Presentation Environment Figment User's Guide H. Command Reference Commands are formed in simple English, typically verb-noun. Figment recognizes its own built-in commands and special user- defined commands. The author of the story uses the user-defined command to create a unique command for special situations ("kiss the toad"). We cannot discuss those commands since we do not know what authors will develop. Therefore this section can only discuss the built-in commands. In the following syntax definitions, "<>" means you insert something at that point in the command. For example, <object> would mean that you would supply an object's name. The symbols "[]" mean that the part of the command enclosed therein is optional. You do not actually type the characters "<>" or "[]". Use the following commands when playing the story. Of course the story author has ways of inhibiting or subverting these commands, so you might not get the anticipated effect, but that is the challenge of interactive fiction. 1. Charm Syntax: Charm <character> The one-shot version of the Hex command that allows you to disengage. You may also skip a wager here, but it costs you a move. See also Fight, Hex and Hit. 2. Close Syntax: Close <thing or feature> The inverse of the open function. Used most often with containers, but may also be used with other objects such as doors. See also: open, lock, unlock. 3. Drink Syntax: Drink <thing> Some things are suitable for consumption others are best left alone. The effects may be devastating or beneficial. Only experience can help you here. See also: eat. 14 Figment User's Guide Presentation Environment 4. Drop Syntax: Drop <thing> Drops something you have in the scene. This is the inverse function of "take". Some places just are not safe places to drop things: >drop the baseball You drop the Baseball and it disappears. Sometimes you have to shed items to make room for new things: >take ball You can't carry any more. >drop bat You drop the bat. >take ball You take the ball. 5. Eat Syntax: Eat <object> You must eat from time to time. Some objects are quite good; some less so. See also: drink. 6. Examine Syntax: Examine [me or <object>] The examine function is very important because it often gives you essential clues. Examination costs you a move, but the information can often be worth it. Players who have played the story before have already examined the thing in question, hence they achieve the goal with fewer moves and they rise to higher levels of skill. Thus skill is a function of experience. The examine function comes in several forms: "examine" by itself will describe the scene. "examine me" will describe you, the player. "examine" followed by an object name will describe the object. 7. F1 - Enter Story Editor 15 Presentation Environment Figment User's Guide Syntax: F1 Function Key Hitting the F1 key enters the editor at the first editing screen or the last screen you were editing if you are returning. The story is unaffected by this action (unless you edit it), and you may safely return to the story as you left it. Hit F1 again to return to the Presentation Environment. 8. F6 - Comand Text Editor Syntax: F6 Function Key The full screen text editor is implemented for editing commands when they fail. This is most often used when you give several command sentences as one command line. If your command fails because of a typo, hit F6, edit the text, escape and hit enter. 9. F9 - Step a log file Syntax: F9 Function Key The step function is used to execute a log file one command at a time. It is implemented as the F9 key. Before you play your log file, you must re-establish the state of the story when the logging process was started. Do this with the "restore" or "restart" functions then hit F9. Each time you hit F9, one command will execute. You can step partway through a file, turn logging on, and log a new sequence of commands. When you play back your log, you will get your original sequence up to the point where you re-enabled logging. From there on, you get your new sequence. It is wise to make an insurance copy of the log before modifying it. The step command does not let you specify a file name. It will use the last log name used, if none was used, then the log name matching the story name. You can step through a log then say: play continue t where t = delay time in seconds The log will then play out to the end automatically. See also: Log, Play, and Save. 16 Figment User's Guide Presentation Environment 10. F10 - DOS Shell Syntax: F10 Function Key You can leave Figment to go to the DOS command interpreter by hitting F10. You may then do any work on your machine that you like (word processing, spreadsheets, document printing, communications, etc.) When you are ready to return to Figment, simply type "exit". You will return to Figment exactly where you left off. This is a useful feature for searching through various floppies for files. If you will be gone a long time, it is probably wise to save your story before you leave. (See the command Save.) This function expects to find the DOS command interpreter, "COMMAND.COM" on the diskette in the default disk drive. You get an error message and remain in Figment if COMMAND.COM is not found. This function depends on your having enough memory to do useful work once you are out of Figment. Use the CHKDSK program on your DOS disk to see how much memory you have once you have left Figment. While you are gone, Figment sleeps in memory awaiting your return. DOS reminds you of this fact so you will not forget, switch off your machine, and lose your work. 11. Fight Syntax: Fight <character> A fight is a battle of strength. You are locked into the fight until it completes, and the only way to complete is for one of the protagonists to die (see also Hit). The odds favor the stronger fighter, but certain objects improve your odds by adding to your strength. Fights are random processes with their outcome weighted by the strengths of the two protagonists. Sometimes weaker combatants win; they just get lucky. Fighting is bad for your health. Lose most of your health and you lose your strength. Lose all your health and you die. You have some control over this process since you can wager the number of health points you want to commit on each cycle of the fight. This implies that you can hit heavy or hit light and receive in kind. For example, if you wager 4 points, the system computes a random transaction and apportions the results: 17 Presentation Environment Figment User's Guide Wager: 4 You hit the <character> 3 times. The <character> hits you 1 times. This means that your opponent loses 3 health points while you lose only 1 point. It also means that your maximum wager is the full number of health points that you have. If you wager more than you have, Figment automatically reduces your wager to your health count. Of course, you might lose them all, in which case you die. You can wager zero health points which means that you skip this random number in the hopes of skipping a possibly unfavorable one. You can skip indefinitely, but you are in an infinite loop requesting wagers so eventually you must commit to a wager. Skipping also costs a move, but considering it can cost several moves to recuperate a lost health point, it can be a successful strategy to skip. Your health recovers with time after the fight. You gain strength and sometimes skill as a result of defeating an opponent. A one-shot form of the fight command is provided as "Hit". See also Hit, Charm, and Hex. 12. Find Syntax: Find <object> This command will locate people and things you have seen before in prior scenes. It will change the scene to the scene where the object is. You cannot find objects you do not know exist, and you only know objects exist by seeing them in scenes. Sometimes you have more knowledge than you realize so it does not hurt to try. This command is subject to any restrictions on path computation. See also the "Go" command for more information on paths. 13. Give Syntax: Give <thing> [to] <character> The forms: 18 Figment User's Guide Presentation Environment >give the book to the boy >give book to boy >give book boy are all legal, but the form: >give the boy the book is not legal. If you do not have the prescribed object in your possession, but it can be found in the scene, Figment will automatically take the object for you and then give it to the character. This counts as a two step action meaning your move count is incremented twice. The "take" action is a fully separate command, which is to say that the Story Designer can impose conditions on that action. See also: put, take. 14. Go Syntax: Go <direction> <[to][the]scene name> As you move in different directions, you change scenes. Directions are given as the four points of the compass plus "up" and "down". Thus: >go north >go up Actually, "go" is optional and the directions can be abbreviated to n, e, w, s, u, and d. So: >n changes to the scene to the north of the current scene as defined by the story map. The "go" command also recognizes the names of places (scenes) where the player has been before. The player can say: go to the river go home go to the basement The scene you specify must be a scene you have been in before, and you must know the directions back to the scene from the current scene (typically by virtue of experience). 19 Presentation Environment Figment User's Guide As you explore different scenes, you acquire knowledge about where scenes are in relation to each other. When you have reached that level of understanding about the story, it is nice to let Figment do the work for you. Figment will compute a path and begin moving through the scenes along the path until the destination is reached. Each scene change along the way is a legal move and is subject to any constraints upon the player that the player would experience if the moves were made manually. If your health or your food supplies are low, this command might exhaust you since each scene change increments the move count. It is conceivable that the destination is known, but the directions needed to construct the path to it are not known. When Figment cannot construct a path, it reports, "You don't know the way from here." The player will have to explore some more by giving the compass directions until more directions along the path are known. Some scenes function like one-way valves. They have no return to earlier scenes. If such a scene lies along your path, the path function will always fail when you try to return to prior scenes. Each change of scene is subject to any restrictions placed on the "go" command in each scene along the way. You may encounter a scene along the way that restricts your leaving until you have performed some special task. In such a case, the path terminates. When you have completed the task, you can continue, if you wish, by repeating your command: "go to the river". The Designer can give you knowledge of places and directions at the start of the story. In which case, the path function can succeed even if you have never been to the scene before. It's worth a try, and it's valuable knowledge if it's true. 15. Hex Syntax: Hex <character> "Hex" is the same as "Fight" except you compete on the basis of magical ability. The one-shot form of Hex is Charm. See also Charm, Fight, and Hit. 16. Hit Syntax: Hit <object> 20 Figment User's Guide Presentation Environment This function is the one-shot form of the Fight command. The command's advantage is that you are not locked in to a fight to the death. It is best reserved for times when your health is low or when you are surrounded by bad-guys and you wish to keep the option to retreat. See also Charm, Fight, and Hex. 17. Lock Syntax: Lock <thing or feature> Used to prevent objects from being opened. See also: unlock, open, close. 18. Log Syntax: Log [name] [on or off] The command: >log on turns on command logging. A log file with the name of the story and an extension of ".log" will be created if none exists. If said file exists, it is opened and commands are appended to the end of the file so previously logged commands will not be over- written. If you want a fresh file, you will have to use "F10" to go to DOS and delete the existing log file before you begin logging. Playback is dependent on the exact state of the scene and its objects at any given time. Thus, unless you save your story before logging, you will not easily recreate the same state so you can play your log back. The command: >log off turns logging off and closes the log file. Typically, you will not see any disk activity until you turn off logging since DOS buffers small writes until you accumulate enough data to justify writing. The command, "log" with no modifiers (on or off) toggles the 21 Presentation Environment Figment User's Guide logging feature from "off" to "on" and vice versa allowing you to stop logging momentarily and turn it back on again when you are ready to log commands again. While logging is "on", Figment warns you by printing "Logging" in reverse video off to the right side of the command line. The log file does not log wagers so you will be re-entering them manually when playing back log files. In order to get consistent results with fight sequences when playing back logs, you will want to specify the seed for the random number generator. The log file is an ASCII file that can be read directly in your text editor. It can also be written by same. See also: save, restore, play, and step (F9). 19. Open Syntax: Open <thing or feature> Used to access the contents of containers. Might also be applied to other objects such as doors. Locked objects cannot be opened. Open containers describe their contents in the Scene Description and Inventory. >open the box You open Pandora's Box. >open the door The Inner Sanctum Door is locked. See also: close, lock, unlock. 20. Pause Command The command "Pause" is an empty command whose sole reason to exist is to be logged in a log file. When the "play" function encounters a pause statement during playback, it stops the playback at that point. Pause is particularly useful with text editing of log text files (see below). Playback can be continued with the command "play cont". Do not confuse "pause" with "wait". See also: Play, Step (F9), Wait. 22 Figment User's Guide Presentation Environment 21. Play Syntax: Play [name] [cont] [delay] The "play" command replays a log file created with the "log" command or your text editor. You will want to restore your saved version of your story before playing back the log file. The playback can be very rapid so you may want to hit your "pause" key to study the responses or use the "step" command (F9) to execute logged commands one at a time. You can slow down the playback by specifying the delay interval between commands. The delay is specified as an integer representing the delay between commands in seconds. Thus "play 5" plays the default log with a 5 second delay between commands. If you strike the key, "i" or "I" while Figment is playing a log, the playback will interrupt playback immediately. The "step" command (F9) may then be used to advance the log file or the playback can be resumed with the continue option. The option "cont" continues the log playback after it has been interrupted or paused. Of course, it also works after stepping a log file any number of moves with F9. The form of the command is: >play cont You can specify log file names in the play command. This means you can play or step to a pre-determined point then switch to a different log. See also: save, restore, log, and step (F9). 22. Put Syntax: Put <thing> [in or on] <thing or feature> Put is pretty straightforward, but the author can inhibit it with certain objects. >put the ball in the box >put the book on the table >put the book on the flagpole You can't put that there. If you do not have the prescribed object in your possession, but it can be found in the scene, Figment will automatically take the object for you and then put it in or on the object. This two- 23 Presentation Environment Figment User's Guide step action is treated as a fully separate command, which is to say that the author can impose conditions on the "take" action and your move count increments twice. See also: give, take-from. 23. Quit Syntax: Quit Ends your Figment session and returns you to DOS. Consider saving your session to disk first. This is the only legal way out of Figment (Ctrl-C works, but it isn't legal). Even when editing, you return to the Presentation Environment side and exit with "quit". Quit shuts down music and switches off graphics mode when those features are used. Ctrl-C does not. See also: Save. 24. Read Syntax: Read [<Object>] If the appropriate story conditions do not hold true, this function just prints gibberish. 25. Restart Syntax: Restart [<Story Name>] This restarts the story at the beginning. If you do not specify a name it assumes you want to restart the current story you are playing. If you garble the name, you get a list of available stories. You cannot restart a story that you saved with the "save" command. Use "restore" for that. See the section on File Management for more information on ".sdf" and save files. See also save, restore. 26. Restore Syntax: Restore [<Story Name>] This reloads a file that was saved previously with the "save" 24 Figment User's Guide Presentation Environment command (See below). If you do not specify a name it assumes you want to restore the story you are playing. If you garble the name, you get a list of available stories. Restore differs from restart. The state of the story returns to the state at the time the story was saved. See also save, restart, log. 27. Save Syntax: Save [<Story Name>] This function saves the story in its current state in a file on the disk with the specified name. Do not specify a file extension. A save file is reloaded with "restore". If you do not specify a name, Figment assumes you want to save the data under the current name. If you specify a name, Figment changes the current story name to that name. Figment keeps the last save file as a backup renamed to a ".bak" extension. In order to use a ".bak" file, you must rename it to a ".sav" or ".sdf" file. You do this with the DOS command "rename". Again, exit with F10, make the changes, return and use "restore" or "restart". See also Top Level Editor, File Management, Restore, Restart, and Log. 28. Script Syntax: Script [on or off] The script command will output the story to a listing file. The resulting text file can be read into your word processor or printed on your line printer. The listing is contained in a file with the name of the story and a ".lst" file extension. This command is modeled after the "Log" command so you should rcognize the usage. While scripting is enabled, Figment prints "Scripting" in reverse video at the right of the command line. It is probably best to play a log file with scripting enabled, but you can also use it when you are giving commands manually. You can toggle scripting on and off by saying "script" with no 25 Presentation Environment Figment User's Guide on/off modifiers. This lets you turn off scripting while you experiment then reenable scripting and proceed. 29. Shoot Syntax: Shoot <object> [with <weapon>] The shoot function requires great skill. The life expectancy of novices shooting weapons is extremely short, but don't take our word for it. Only certain weapons qualify as weapons that can be shot. You would not shoot a sword for instance. This function gives you an alternative to fighting on the basis of magic or strength. If you have more than one suitable weapon, you must specify which one to use. 30. Take Syntax: Take <thing> [from <object>] You can take a thing from the scene or, optionally, from a character or feature in the scene. You get an error message if you attempt to take the character or feature itself or if you simply mis-type. >take the amulet You take the Amulet of Zendor. >take the keg from the Saint Bernard You take the Wooden Keg. >take the Saint Bernard You can't take the Saint Bernard. >take the #$%^# You can't take the #$%^#. 31. Toggle Syntax: Toggle Changes the Scene Description from the long-hand description to the short-hand description. Whenever you return to a scene you have been in before, you get a short-hand description. This will change the display mode back to the long-hand description. 32. Unlock Syntax: Unlock <thing or feature> 26 Figment User's Guide Presentation Environment Many things must be unlocked before they can be opened. In many cases, finding the keys that do this is the central theme of the story. 33. Wait Syntax: Wait [number] Skill suffers by waiting, but health can recuperate. If you specify a number, Figment will wait that number of moves. Any events that would normally transpire on those moves will still take place even though waiting is in itself an empty command. 27 The Story Editor Figment User's Guide Part II. The Story Editor Part II discusses the mechanics of editing. Use it as your editing reference when you want to know how to change something. The "what and why" of editing is discussed in Part III once you understand the mechanics. A. Introduction to the Editor The Editor is comprised of several data entry screen editors that allow you to change important story elements, including the story logic, with a few simple keystrokes. You can enter the editor at any time before or during play to fix a bug. Similarly when developing material in the editor, you can switch to playback mode and see immediately how it plays. You will understand the editor much better if you have a working example in front of you. Call up the demo shipped with your software and follow along with the discussion trying each topic. You cannot damage the original data so, by all means, experiment at every stage of the discussion. Hit the F1 key to flip back and forth between the story and the editor. Try it now. B. Theory of Operation With Figment, you create objects and scenes. The objects represent characters, props, and features in the scene. The scenes represent places where the objects reside. You associate the objects to their scenes by making a link from the scene to the object. Scenes are tied together by the Story Map. With the map done, you can use the "go" command in Presentation Mode much like walking through the rooms on a house tour. Without a map, you are stuck forever in the first scene. You write rules to govern the object behavior. The collection of all rules is called the story logic. Without the logic, the story is lifeless; the player can manipulate the objects, but nothing exciting happens. C. How to Make an Interactive Story From the above, you should recognize a simple procedure for creating a story: Create objects 28 Figment User's Guide The Story Editor Create scenes Link objects to scenes Create map to relate scenes one to another Create logic Of course you need not create all your objects before you create scenes, etc. You just need a few to get going. You can add more later. The map gives your story structure so the first few sessions are aimed at building up the map so you can take the house tour. Logic development is the hardest so postpone it until you have sketched out your story with scenes and objects. It is easy to develop "Paralysis by Analysis" so do not get too deep into logic development too soon. Many secondary data structures are used to embellish the story: object types, link types, attributes, and profiles. You add these as you need them to make the rules so do not concern yourself with these too early in the project. The Player Map is made for you automatically during play, but you can fill it in if you want to give the player foreknowledge of places and things - another embellishment. Use command logs. Make one very early in the project and use it to drive your development efforts. When you make a log in playback mode, you can only log commands that succeed, but if you make the log in your word processor, you can deliberately add commands that you know will fail. Why? Because a log made in Figment represents completed work, but a log made outside of Figment can represent future work. The log fails in the early going, but as you develop more data and rules you progress further and further until finally you can complete the entire log. You then go back and make a harder outline and repeat the process. Also learn to insert "Pause" commands at points where you know the log will fail, then you can experiment manually. And since you need to use logs so much, you will probably want to fix the random number generator so get used to starting Figment from DOS with the command form: figment <story_name> <seed_number> The first log you write is probably only the commands required to navigate through the scenes to the final scene of your story. Gradually you add activities within the scenes developing the rules for them. Single step through your log and take notes of things you want to change. Change your log first. Change the logic as required to make the log work. 29 The Story Editor Figment User's Guide Recognize that what you are making is really a model. Although the model can improve, it can never really be finished since you can always add more conditions by expanding the log file or writing a completely different one. But eventually, the model becomes sufficiently large to encompass a large number of situations and demands placed on it. At that point, you probably deem the work "complete enough". D. Method of Editing The method of editing could be described as a "Poor-man's Mouse" interface since you will be navigating across the screen with the cursor control keys and in many cases changing values with them. Figment is remarkably fault tolerant. The two most notable areas where it is not are the areas of file management and deleting objects. In both cases, Figment is obliged to assume that you want the command performed and so performs it. It is your responsibility to understand the full ramifications of these commands. To that end, special sections on these topics are provided late in the editing discussion when you have a better understanding of the editing operations. Until you reach that point, we recommend that you do not do these operations. 1. Scrolling Values Except where text is specifically required, you merely position the cursor over the data value you want to change, then hold down the up- or down-arrow cursor keys until you reach the value you want. Release the key, and the new value is set. We call this process "scrolling the data value". Most data values are set this way so you will hear the term many times in this document. Usually different data types are displayed in different locations so when scrolling values, there is never any confusion about what is being changed. In some cases (notably expression editing), different data types can be used in the same location. When this occurs, we use the "Home" key to change the data type then we use the up-/down-arrow keys to scroll the data value. Pay particular attention whenever we discuss the Home key, because it is not obvious from looking at the screen that the Home key can be used. 2. Navigating the Screen In order to scroll a data value, you have to move the cursor around the screen to the value's position. There are two pairs of keys that will do that. The left-/right-arrow keys move the 30 Figment User's Guide The Story Editor cursor within the current editing level. We call this "advancing the cursor". The Page-up/Page-Down keys change the current editing level. Often, you must step down through several mini- levels. The Escape key is used as a super-exit key when you want to leave these levels and move on to another task. 3. Text Editing Text can be changed in two ways. You can simply type in new text to replace the old text, or you can use a full screen editor. Typing is the easiest way when the text is small such as object names. Your editing capability in the typing buffer is limited to the backspace key for correcting typos however. Often, you begin to write a little message and end up writing a monster several sentences long riddled with corrections you would like to make. No problem. Just hit F6 and the text is swept into the full screen editor. The full-screen text editor pulls the text into a buffer where you can use common word processing commands to move around in the buffer and change the text. This is the preferred text editing method for the longer messages you want to write. A separate section of this document is devoted to the full-screen text editor. Any text item can be up to 2 KBytes long, including names, which is about a full screen completely covered with text. Considering that scene descriptions and command responses are composed of several text items, you can compose screenfuls of text if you desire. Bear in mind that this costs computer memory, but you should find that your imagination is taxed before the system is. A text item can be "erased" (set to length zero) simply by striking the key labeled "Enter" (or "Return" on some keyboards) instead of typing text when the cursor is positioned over the text item. In fact, it is so easy to do this we caution you to stay away from the Enter key until you are sure you want it. Text strings that you write are passed around during play and may be used in several different places. Often they are grouped together to form paragraphs and they are added and removed from that paragraph as the play progresses. Figment runs the paragraph through a low-budget pretty-printer which breaks the lines at word boundaries. Therefore, if you attempt to force some artificial format on the text within the editor, it can often look wrong at run-time. Similarly, hyphenating produces unexpected results at run-time. Unless the word is actually a hyphenated word, it is best not to 31 The Story Editor Figment User's Guide insert additional hyphens. Ignore end-of-line restrictions and simply type blindly away. When the cursor reaches the end of the line, it simply wraps to a new line and keeps on going. This produces lines with words that wrap in the middle, but as we said, Figment cleans this up at run-time. You can always use hard-returns if you want them, and you need them for paragraph breaks, but you must use the full screen editor to enter them, because they terminate the typing buffer. 4. Error Message Reports Most errors are simple mis-steps and only merit a beep. Larger errors report to the second line of the screen. The message remains until you hit another key. E. Cut, Paste, and Insert Functions Cut and paste operations have been implemented for some data structures, but not all. We discuss the general nature here and cover details on a case-by-case basis for each data structure. These functions are context-sensitive, meaning you get the correct cut-paste operation for the item on which the screen cursor is positioned. 1. Insert The "insert" function is designed to open a gap in a list of data elements and leave you a new data item for editing. It is used wherever the order of items is important. Currently, it is implemented for rule bases, expressions and rule messages. You insert a new data item into a list or sequence by hitting the Insert key when the cursor is positioned over the item where you want the new item inserted. 2. Cut - F7 The cut function (F7 key) parks a data structure in a buffer temporarily for pasting to a new location in a list or sequence. It is implemented for text strings of all kinds, rules, and expressions. Different cut buffers are used for each data type. Cutting one data type will not overwrite any different data type parked in 32 Figment User's Guide The Story Editor its cut buffer. It does, however, overwrite the existing contents of the buffer when you repeatedly cut the same data type. Text strings can be cut anywhere they are used in objects or rules. They can then be pasted back in new places. This means that you can cut description strings out of objects and paste them back as rule messages and vice versa. The F7 key will cut a text item whenever the screen cursor is positioned at the start of the text. You cannot take half a string. Cut the whole string, paste a copy back and edit the two strings separately. The cut buffers are not written to disk so they do not carry over between sessions, but they are unaffected by play or file read/write operations. 3. Paste - Alt-F7, Shift-F7 The paste function pastes a copy of the appropriate cut buffer to the new location as indicated by the screen cursor. If the cut buffer is empty, meaning you forgot to cut something, the paste function just beeps. When you paste a text string in an object (description or examination message), the old string at the cursor location is deleted and replaced with a copy of the string in the cut buffer. You can move to another location and paste another copy of the same string. For object text strings, the Shift-F7 and Alt-F7 keys are synonymous. You can use either key. Sequences behave slightly differently. When you paste something in a list or sequence, the existing items are bumped back in the sequence, and the item in the cut buffer is inserted in the sequence. Repeated pastes make multiple copies. Rules in rule bases, expressions in clauses and rule message lists are all examples of items in sequences or lists. The two different paste keys, Shift-F7 and Alt-F7, are provided so that you can insert items in the sequence differently. Shift- F7 inserts the item into the sequence after the item your cursor is pointing to. Thus if your cursor points to item number 7, the newly pasted item becomes item number 8 and the cursor advances to point to it. Alt-F7 inserts the new item before the item your cursor is pointing to. Thus, item 7 becomes item 8 and the newly pasted item becomes item 7 to which your cursor is still pointing. 33 The Story Editor Figment User's Guide Alt-F7 appears most like the traditional paste operation used in word processors so it will seem most natural to you. Shift-F7 is used most for tacking items onto the ends of lists and sequences, a frequent task. F. The Top Level Editor The highest level in the editing hierarchy is the Top Level Editor. It calls the different screen editors for the different Story Elements. You also read and write many data files from the Top Level Editor. You enter the Top Level Editor from the Presentation Environment by hitting the F1 key. This puts the first screen editor on the screen, the Stuff Editor. The Top Level Editor is always displayed as the top line in any other screen editor (except the text editor). The editor will warn you when you attempt to edit data or write data to disk that has been changed during play: Warning! Data changed during play. Proceed? (Y/N) You have the choice of proceeding with your action or retrieving the data from disk (Use Shift-F2. See File Management). You will only be warned once; if you proceed to edit the altered data you will not be warned if you write it to disk. You return to the Presentation Environment via the Page-Up key from the Top Level Editor or by hitting F1 from anywhere in the editor. Try moving in and out of the Editor hitting F1 and Page- Up: F1 to enter Story Editor from Presentation Mode F1 or Page-Up to exit Editor to Presentation Mode The different screen editors form the next level down from the Top Level Editor. You can view these different editors with the Up-/Down-Arrow keys when the cursor is positioned by the element name, which it is when you enter the Top Level Editor from the Presentation Environment. Each time you hit the key, the next screen editor is displayed. Note that as you keep hitting the Up-arrow key you come back around to the first screen and that the Down-arrow moves through the list of screens in the opposite direction. This philosophy is common throughout the Story Editor; every key has its opposite number and lists are scrolled through to the end whereupon they "wrap" back around and start over. For long lists, it is often 34 Figment User's Guide The Story Editor easier to go backwards one step from the beginning to reach the end. The Top Level Editor also controls file input/output, but we will postpone that discussion until later. Just note here that you move over to change the filename with the Left-/Right-arrow keys. As with the Up-/Down-arrow keys you get the cursor-wrap and forward-reverse effects. F2 and F3 will read and write files respectively anytime your cursor is anywhere on the top line so don't hit them until you want to modify files. You can leave Figment and return to DOS temporarily by hitting F10 when in the Top Level Editor only. This does not terminate Figment. It leaves it sleeping in memory until you return with the DOS command "exit". This lets you change filenames or disks before doing file I/O operations. F10 is enabled anytime your cursor is anywhere on the top line of the editor screen. As mentioned in the Command Reference, F10 requires the file "COMMAND.COM" to be on the diskette in the default drive. So far, we have viewed different screen editors, but we have not entered them. Do that with Page-Down. Page-Down means "Enter lower-level editor". Correspondingly, Page-Up means "Exit to higher level editor". Change to the screen editor titled "Stuff" using the Up-arrow key, then hit Page-Down. Your screen cursor jumps down to the next level which displays all the "Stuff" that have been defined for the story. G. Summary of Editing Operations At this point, we have demonstrated much of the major editing features so a brief summary is in order before we continue. Figment assigns its editing functions to special keys so they are executed with single keystrokes. The key assignments are as follows: Summary of Editor Key Assignments Up-/Down-Arrow means change the value of the item on which the cursor is sitting. We call this process scrolling the value. We deliberately use the word "scroll" in the remainder of this document to mean these arrow keys. Right-/Left-Arrow means advance to the next item on a given editing level. We deliberately use the word "advance" in the remainder of this document to mean 35 The Story Editor Figment User's Guide these arrow keys. Page-Up/Page-Down means change to the next level of editing operations. Hit Page-Up enough times and you find yourself back in the Presentation Environment. ESC - Escape is a super-page-up key. Probably preferred to Page-up since it cannot over-shoot the Top Level Editor. It is a rapid exit from deep levels. F1 enters the Editor from the Presentation Environment. It also is a rapid exit from any level in the editor to the story. Repeated strikes on F1 toggles back and forth between the editor and the story. F2 reads the file whose name is given on the top line of the screen. F2 only works in the Top Level Editor. F3 writes to the file whose name is given on the top line of the screen. F3 only works in the Top Level Editor. Shift-F2 reads the saved data file, the ".sav" file. Similar to "restore" in the Presentation Environment. It works only in the Top Level Editor. Shift-F3 writes a save file, the ".sav" file. Similar to "save" in the Presentation Environment, but there is an important difference - it sets the data to starting conditions so the ".sav" file can be renamed a ".sdf" file. Top Level only. F4 generates a listing file of the currently displayed object type or rule base. F4 is only enabled in the Top Level Editor. Shift-F4 generates a full listing file of all the objects or all the rule bases in the database. Shift- F4 is enabled in the Top Level Editor. F5 alphabetizes the stuff or scene objects depending on which screen you are viewing. Implemented at the object name level only (not the Top Level). F6 invokes the full-screen text editor. ESC exits this editor and returns to the Story Editor. Enabled whenever the cursor is positioned over a text item. F7 - Cuts a text string, rule or expression. 36 Figment User's Guide The Story Editor Shift-F7 - Paste, the opposite of F7. In a sequence, it pastes after the current item. Alt-F7 - Paste also. In a sequence, pastes before the current item. Insert - Inserts (opens) a gap in a list or sequence. F10 exits Figment temporarily to DOS. "Exit" returns you to Figment. F10 only works in the Top Level Editor. "+" creates new things: objects, links, rules, expressions, etc. "Delete" deletes things created with "+". "Home" used mainly in expression editing to change data types for scrolling values. Also negates conditional functions. If you attempt to think of these keys as cursor movement keys, you will have a very hard time in the editor. The cursor has a mind of its own and moves where it must to point to your position in the editing hierarchy. In short, if you're trying to follow the cursor, you're in trouble, because it's following you! In practice, we break this convention in only a few places: in the full-screen text editor, the keys are used as they are in most word-processors, for example Page-Up moves to the top of the page; in the object editors we move through a matrix of names up, down, left and right with the arrow keys since it seems more like a full-screen text editing operation; and in label editing, we allow the up/down arrow keys to move up and down a list of names since scrolling is not used there. Once you make this conceptual leap, you should find that a great many editing operations resolve to only three key-pairs. Play alters the data so you must write your editing changes to disk before starting play or they will be lost. A rigorous editing procedure would dictate that you should enter the editor, examine data structures to identify a problem, retrieve the save file from disk, make the changes, put the data back on the disk, return to the Presentation Environment, and play through to see if the correction was valid. H. Stuff Editor 37 The Story Editor Figment User's Guide The first thing to do in developing the story is to create some objects to play with. Objects come in two types: Scenes and Stuff. "Stuff" are best defined as objects that are not scenes. Stuff comes in three types: "Things", "Features" and "Characters". Stuff and Scenes are identical data structures except that they are stored in different places. Therefore, if you learn how to edit Stuff, then you know how to edit Scenes. Objects are large and only a portion of the data can be displayed at a time. If you want to study all the object data, you can dump it to a listing file by hitting the F4 key when in the Top Level Editor. This will dump all the stuff objects or scene objects depending on which type is displayed when you hit the key. The data is written to a file with the same name as your story but with a ".lst" extension. You can print this on your lineprinter with the DOS "print" command. Use F10 to invoke a DOS shell so you can type or print this file. You enter the Stuff Editor from the Top Level Editor by displaying the screen labeled "Stuff" using the Up-Arrow key. You move down one level from the Top Level Editor to the Stuff Editor using the Page-Down key. You exit the Stuff Editor by moving up one level to the Top Level Editor with the Page-Up key. 1. Stuff Names When you enter the Stuff Editor, you see the names of all the stuff that have been defined for the story. Your cursor lands on the first name which is lit in reverse-video. The names are displayed in a row-column matrix. Hit the right-arrow key and hold it down. The cursor and reverse-video box advances sequentially to each object name. The matrix of names can be large, so we break convention and use the up-/down-arrow keys to move up and down rows within the matrix. You can change any object name by typing a new name in its place when the cursor sits on that object's name. Names are text which means you can make them up to 2 KBytes long if you like. We display only the first 15 characters. When you hit return, the new name is entered in place of the old name. It is bad practice to leave object names blank although it is harmless. As with all text items, you can also hit F6 and use the Full Screen Text Editor, but names are short so typing is easier. Anytime you change an object name, that change is immediately reflected throughout the story. You never have to go around the editor changing each occurrence of the name wherever it is used. 38 Figment User's Guide The Story Editor You can duplicate names, but it is bad practice. Also names that only partially duplicate existing names can cause some confusion for inexperienced players. If you have two objects, one named "Red Ball" and the other named "Blue Ball" and the player says "Take ball.", the system responds with the first ball found, red or blue. Avoid punctuation in names. Names like "Mr. Johnson" should omit the period since that will be mistaken for a sentence terminator. Upper/Lower case does not matter; use what you like. 2. Creating and Deleting Objects If you want to create new objects, hit the "+" key any time your cursor is in the matrix of object names. The new object is added to the end of the matrix and labeled "(Undefined)". There is no special order required of objects. They can be created at any time. You just make them when you need them. You can make several at one time and fill them in later. Any object named "(Undefined)" will not be written to disk (See the discussion on File Management later in this document) so it will eventually disappear with any subsequent file write/read operation if you do not use it. Thus new objects should be given at least a working title if you want to keep them around. When the object list exceeds the space available to display the names, the list can be scrolled. Simply move the cursor down any column of names in the matrix of names. When you reach the bottom row, the matrix begins scrolling row by row until you reach the end. If you create more objects than can be displayed, you may think that nothing is happening, but scroll the name matrix and you will find them at the end of the list. When you can create no more objects, Figment beeps as you strike the "+" key. Deleting objects is slightly harder. Advance the cursor until it is over the object you want to delete and hit the "Delete" key. This is easy enough, but it has created some problems for you. Objects are the fundamental building blocks for the stories. Many story elements refer to them. Now that you have deleted the object, these other elements have nothing to refer to. Figment inserts a dummy reference temporarily until you can change the reference. You will have to work through the editor and change or eliminate these references. You will see them marked "(Deleted)" in object link lists, rule bases, and maps. A full discussion of deleting objects is deferred until after you have an understanding of the full editing process and the 39 The Story Editor Figment User's Guide aforementioned object references. For now, we recommend that you consider re-naming an object instead of deleting it. All of the references in other story elements will then reflect the new name. 3. Alphabetizing Objects It is convenient to arrange the names in alphabetic order. You can do that simply by hitting the F5 key when the cursor is in the name matrix. You can do this anytime you add a new object or change an object name. You have done all that you can do at this level. You can move down a level and change the object's data with Page-Down or you can return to the Top Level Editor with Page-Up. When you move down a level, the object's name remains lit in reverse-video to remind you which object you are editing. 4. Player Object The first object in the Stuff List is the Player Object. You cannot delete this object. The name of this object is changed to reflect the player's name given in the entry dialogue when Figment is started. (See "Getting Started".) You are free to edit this object, but its type remains "Player" and cannot be changed. Neither can you alphabetize this object. Regardless of the player's name, this object never moves from the first position. 5. Object Data Selection Page Down from the Name Level and you can choose the data you want to edit. See the line labeled: "System Attributes Text User Attributes Links" Your cursor lands on "System Attributes", and they are displayed. As you move the cursor left or right, the various data types are displayed in turn. If you Page-up from this level you return to the name level, and the data type you selected is displayed for each object as you cycle through the objects. Stop at the data type you want to edit and hit Page Down to enter that level. a. System Attributes 40 Figment User's Guide The Story Editor This presents the attributes and flags required for the built-in functions. It also includes the user-defined object types. Your cursor lands on the attributes. Advance the cursor to the flags or the object types if you want to select them. Hit page down to enter the level of your choice. (1) Attribute Editing Each attribute is used by a particular built-in function so attributes control how objects are used. Except for the Type attribute, you need not worry about any other attributes until you use functions in the story that need them. You can also use the attributes in rules that you write: If { Player is linked to Obj Sub-Typ Money }... This would mean, "does the Player have anything valuable?" Changing the object's Type attribute from "Thing" to "Feature" means that people cannot pick it up and carry it to another scene, for example an object called "Weather" is a feature of a scene. As mentioned earlier, the object type will not change on the Player Object. The sub-type is used mainly with objects of type "Thing". Objects of sub-type Armor or Weapon are used in fighting. Objects of sub-type container report their contents when they are open, meaning when their "Open" flag is set to read "OPEN". "Food" means the object can be eaten. "Strategic" means it is a weapon that functions at a distance; it can be shot. Potions can be drunk. Scrolls can be read. "Goody" is a catch-all. If you do not know what something is, call it a goody. "Money" means the object has monetary value. Leave the sub-type alone until some function requires you change it. See Part III. Strength, health, magic, size, and weight are numeric values, scroll them up or down as desired. They range from -127 to 0 to 127. Note that they can be set to negative values only for objects of type "Thing", but read the discussion on them in Part III before using negative attributes. You will probably want to specify a health value for any character you create since this is important for conflicts. Note as well the way that numeric values change when they reach very high or very negative quantities. By the nature of binary math, a signed 8 bit integer becomes -128 when you increment past 41 The Story Editor Figment User's Guide +127. The limit attribute specifies the maximum number of links you can make to other objects. It is used, for example, to tell when the player cannot take any more things or when you cannot put any more things in containers. This numeric quantity varies from 0 to 32, the maximum links allowed. It is probably best to leave it at 16 until you know you want more or less. The editor will not let you set this value lower than the existing number of links for the object. Some objects would never have objects linked to them, for example objects of sub-type food. This means the limit attribute can be used to mean something else. In the case of food, the limit attribute means the food value. See the discussion on food in Part III of this document. Similarly, the limit means the number of shots available for strategic weapons. Again, you are referred to Part III for more detail. To edit attribute data, advance through the attributes until you arrive at the one you want to change. Hold the Up- or Down- Arrow key down and the values will scroll. Release the key when you reach the value you want. Exit this level with Page-Up regardless of your cursor position. (2) Flag Editing Flags are special (one-bit) attributes used to indicate the state of the object or permission to modify that state. The flags are changed both by functions in the rule bases and by functions available to the player during play. During the course of the story, the player, via the story commands and the author, via the logic, will be modifying the flags. The flags are edited in the same manner as the attributes so we need not repeat those instructions. A flag only has two states that depend on the type of the flag: ON or OFF, TRUE or FALSE, YES or NO, etc. You see these displayed on the Flags line. Flags are grouped in pairs. The first flag in the pair is the permission flag for the pair. It indicates whether or not the player should be allowed to modify the second flag in the pair. Permission flags are set to read "YES", meaning permission granted (the player is allowed to modify), or "NO" meaning permission denied. Whenever permission is denied and the player attempts to modify a flag during play, the message "You are not allowed." is returned. The Lock-permission flag disables the story commands "lock" and 42 Figment User's Guide The Story Editor "unlock". You typically want to leave them disabled except for specific objects you want players to unlock. The Lock flag controls the story commands "open" and "close". Objects can be locked open or locked closed. Locked objects return the message, "You can't. It's locked." if you attempt to open or close them during play. The Open-permission flag also controls the open and close functions during play. Typically it is used so the Designer can control the Open flag via rules. In addition to reserving the flags for exclusive use, the permission flags prevent the player from making silly constructions such as opening a character. The Put-permission flag is used to indicate if the player can put an object ON this object. The Put function also has a form, Put- in, that is used with containers. That form also checks the permission flag. The Put flag itself is used to indicate if there is an object on this object. Some objects are ambiguous and can take objects placed in them or on them, e.g. a chest of drawers. This flag resolves the ambiguity later when you attempt to describe the object. Further discussion of flags is deferred to Part III. (3) User-Defined Object Types The System Type attribute tells you an object is a "Thing", but is it an automobile or an airplane? A Louis the XIV table? User-defined Object Types let you add more descriptive labels to objects. They are a more advanced topic, however, and beginners need not be concerned about them. User types are labels that you create separately. They have their own editor to define the labels as part of the Parameter Editing Screen (see Parameter Editing). All you do here is scroll through the list of labels that you defined on the Parameter Editing Screen. You might for example set the object type to character, the sub- type to container (so the system will report the object's possessions) and add the user type label "Waiter". Then you could tell if there is a waiter in the room with a menu or perhaps your dinner. 43 The Story Editor Figment User's Guide Editing the object's type labels is easy. From the System Attribute level, advance the cursor to the title "User Types". Hit Page Down. Hit the "+" key to add new type labels. Scroll up or down to change the label. Hit "Delete" to remove an unwanted label. Advance through the labels with the Left- and Right-Arrows. "Escape" or Page-Up exits this level. The order of the labels is not important. An object either has a label or not. The various functions merely test for the label. You will notice that the system will not let you duplicate labels. You have conditional and executional functions to test and modify the user type attribute in your rules. b. Text Figment pulls the text from the object and uses it to build scene descriptions or examination reports. The text that you write here merely represents the initial conditions for the objects. The rules that you write can replace these descriptions with different ones. That is how the story changes with the Player's actions. Descriptions come in two forms: Long and Short. This is just for variety, and it can be a handicap during development trying to maintain both descriptions so you might want to focus on one and ignore the other. Usually this means you ignore the brief description since the long description is the default mode. If you do not write a description of the object, it will be invisible during play. This is legitimate, and often, too many object descriptions make the resulting composite scene description too clumsy so you blank some out. When making a new object, you usually write something trivial like, "Here is the x...", so you can see that you successfully linked the object into the story. Later, you change the text to say something more appropriate to the story. The examination message is reported to the command window during playback whenever the player examines an object. It is optional so you can ignore it until you need it. We described how to edit text earlier, but remember that they cannot exceed 2048 characters in length, and they can be edited by typing over them and/or by hitting F6 to invoke the full screen text editor. You have by now perhaps noticed that long text is displayed as a 44 Figment User's Guide The Story Editor single line followed by "(...More)" implying that there is a longer text string than is actually displayed. If you want to view the full string, hit F6. This puts you in the Full Screen Editor. It is assumed that you want to be here anyway if the text is longer than a single line. Hit "ESC" to exit the editor. Figment is unique because it can change the story depending on who is speaking. The Player can see another character in the scene and change to that character and see the story through that character's eyes. We call that process "Changing the Actor". Figment does that with Viewpoints. (1) Viewpoints A viewpoint is a set of description and examination messages written from the perspective of a character in the scene. We will call them simply views for short. If you purchase the optional graphics and music packages, you can assign images and music to the viewpoints as well. Any object can have up to four views, but it always has at least one, the default view a.k.a. the "Player's Viewpoint". As Figment builds the Scene Description during playback, it searches the scene and each object in the scene for views that match the current Actor. If no view for the Actor is found for the object, it uses the text in the Player view for that object. You label each view for an object (Except the first, it's fixed to "Player".) as being the viewpoint of some character. Of course if you do not have three characters defined (beyond the Player), you cannot have the four total views. Figment will not let you duplicate viewpoints. When you add a new view, Figment chooses the next character from your list of objects that does not duplicate an existing view for this object. You can then scroll the character names to find other legal candidates if you like. The character viewpoints for your objects need not be the same viewpoints for all objects unless you want them to be. Also, many objects appear the same to everyone so other viewpoints are not required; don't feel you have to define viewpoints if you do not want to. The actor currently defined in the story is shown at this level. If you have changed the Actor in the story, you see that name here. Otherwise, it reads "Player". The system automatically displays the "Actor view" when you enter the text level editor. Most of the time, this will be the Player View. 45 The Story Editor Figment User's Guide Editing the viewpoints is simple. From the word "Text", hit Page-Down. Your cursor lands on the view number. If there are more than one view, you can cycle through the views by scrolling up or down. Add a new view by hitting the "+" key. You can delete a viewpoint by hitting the "Delete" key when the cursor is positioned over the number of the viewpoint you want to delete. Rules can refer to viewpoints in the "Copy msg" function. When you delete a viewpoint, no effort is made to change such a reference to the deleted viewpoint. They simply become ineffective since there will be no destination for the copying. Advance the cursor to label the view by scrolling the character names until you see the one you want. Advance onward and edit the text in the usual manner. You can change the Actor here if you like, but remember it changes the actor for the story so be sure to put it back when you are through. Advance the cursor to the Actor name and scroll the character names. When a character name for the Actor matches a name for a view, the text on the screen will change to that view. You can Page-Up to the object name level and display this Actor's view of each object as you advance through the object names. c. User-Definable Attributes Put the cursor over the word "User Attributes". The attributes for this object are displayed. The original premise for user-defined attributes applies to characters, but that does not limit them only to the characters or to human attributes. We will begin by discussing characters and expand the philosophy later to include other needs. Writers are taught to develop characters along three lines: physical, psychological, and spiritual. Figment groups user- definable attributes in three categories called simply Types 1, 2, and 3. You can establish the convention within your work that Type 1 attributes are the physical attributes and Type 2 attributes are the psychological ones etc. Attributes for a hypothetical character might be: Type 1 Type 2 Type 3 Strength 50 Courage 10 Devotion 10 Beauty 20 Bravery 2 Purity -40 Warts 10 Paranoia 33 Je ne sais quoi 100 46 Figment User's Guide The Story Editor Bad Smell 15 DrinksLikeFish 99 Chemistry 12 Dresses Funny 10 Morals 0 Kind to Animals 23 Intellect -10 User-definable attributes are merely text labels that you add to the system on a separate editing screen (See Links and Attributes later in this document). As you can see from the example above, the labels can be anything you can think of. Once you have defined them for the system, you can add them to your objects here by scrolling those previously defined labels and setting their value. The value can range from +127 to -128. You need not specify a value if you do not want to. It might be best to wait and see what values are required as you test your story. User Attributes are used in character profiles (See Profiles below). These allow you to specify a decision matrix for special situations or character types. You also have conditional and executional functions to test and modify the attributes in your rules. We said that user attributes can be used for inanimate objects too. Consider attributes for an object like an airplane: Type 1 Type 2 Type 3 Engine 50 Turbulence -10 Airframe -32 Fuel 10 Attitude 20 Icing 10 From this you might surmise the engines are running fine, the fuel's getting low, the turbulence is getting bad, and that crack in the wing has you worried. Hope the de-icers hold out. Notice that the concept of Physical, Psychological and Spiritual attribute types does not apply when you are not speaking of characters. Hence we call them simply Types 1, 2, and 3. The purpose of the three categories is so that future functions can operate on the groups if desired. For example, if you defeat an opponent in battle, you might win or acquire their physical (Type 1) attributes, but if you fall in love you might share (average) the spiritual (Type 3) attributes. Currently the major activity for user attributes is in Character Profiles (See Profiles below), which allow weight factors to be applied to groups of attributes based on their type. Editing user attributes is easy. Page Down to the attribute line you want to change. Move the cursor left or right to the 47 The Story Editor Figment User's Guide attribute or value you want to change. Scroll as required. If you do not see an attribute you want when scrolling, go to the editing screen for Links and Attributes and define one. Page Down will move the cursor down and add more attributes when you hit the end of the list. The delete key will delete the attribute the cursor is pointing to. The "+" key adds attributes without moving the cursor. Page-Up moves the cursor up and eventually exits this level. "Esc" immediately exits this level. d. Link Editing Links are associations between objects. There are many ways that objects might be associated. Figment lets you label the links to represent these different associations. For example, consider the many ways that John and Mary might be related: Lovers Family - spouse, sibling, children, parents, cousins Classmates Work-related Church Group Tennis Match . . . Knowing the type of relationship tells you more information which means you can write more complex rules with link types, but you are not required to specify the type of link if you do not want to. It is just an option to enrich the story. The default link type is "Generic", meaning "no implied type", and you may use it for all your links if you like. Even if you know the relationship, you do not know the strength of the relationship. Figment lets you model the strength of relationships by including an optional value. You can test or change this value from the story logic. If { John is linked to Mary by Romance > 20 }... The size of the number implies the strength of the relationship. Negative values are allowed. Again, do not be concerned with values for the links in the early going. They are another refinement for advanced users. Link types are defined on their own editing screen (See Links and 48 Figment User's Guide The Story Editor Attributes, below). Here, you merely scroll those types you have defined previously. The most common use for links is associating objects with scenes. When the Player says "take the ball", Figment breaks the link from the scene to the ball and makes a link from the Player to the ball. The story's Scene Description no longer mentions the ball, because that link is gone, and the Inventory reports the ball in the Player's possession. In truth, nothing really happens to the ball at all! The system is wide open. You could link everybody to the ball, and it would appear as though everyone had the ball. The method for editing links is similar to that for user attributes. The limit attribute for the object specifies the maximum number of links you can make up to a final limit of 32. (See the discussion on links in Part III.) The system lets you make duplicate links, but duplicate links can confuse your logic. Check your design and correct it if necessary. I. Scene Editor Once you know how to edit Stuff, you know how to edit Scenes since they are the same data structure and the same editing style. Most attributes are ignored for scenes. They are there only for the purposes of standardization with stuff. You may want to use the lock and open flags when you get to writing rules. They can be used safely. Also, the limit attribute affects the link count as with the Stuff objects. Links are important to scenes. Scenes are not much to look at by themselves. They get their richness by virtue of the stuff that you link to them. The order in which you create links can be important too since they affect the description paragraph for the Scene Description during play. When Figment composes the Scene Description in the Presentation Environment, it looks at the link list for the scene to see what descriptions to use. The first line of text comes from the scene object itself, its description line(s) are from the scene description that you see when you display the scene in the editor. Then it gets any feature description text from any feature stuff that are linked to the scene, then the character 49 The Story Editor Figment User's Guide descriptions, and finally, any thing descriptions. Thus the story's Scene Description flows from what the scene is like, to who is in it, and finally to what you can take from it. As events occur, either by your action or the story's, they may alter the scene so the description is re-composed and re- displayed. If no changes occur, then nothing happens. You are not required to link the Player Object into the scene, but when you do, the player's description is added to the scene description just after the scene object's description. Since features automatically come before any characters anyway, you need not worry about placing them in front of characters in the scene's link list. You need only get the features in the order in which you want them to appear relative to each other feature. The first feature description you want to appear must have its object name appear ahead of any other feature on the scene's link list. The same applies for the characters and the things. All this points to the importance of setting an object's type attribute when you create new stuff as we discussed earlier. That is all there is to editing scenes. We will use the scenes to construct the Story Map. J. Story Maps Earlier, we recommended a methodology wherein we said you should make objects, make scenes, link the scenes to their objects, and build the Story Map so we will discuss maps next. Figment supports two kinds of maps: the Story Map and the Player Map. The Player Map is a luxury we can ignore for now. 1. About Maps The map ties the scenes together. In it, you specify each scene's neighbors and what direction to go to reach them. Maps usually are only edited when you add new scenes to the story or delete old ones or when you want to change the exit directions. You do not edit the map just because you modified the scene or its name. If you change a scene's name, you immediately see the new name when you switch the screen to view the map. You are not obliged to use all the scenes you have defined. In fact, scenes are not really in the story until you put them in the map. Scene-change operations will not work in the story until you make a map entry for your scene. 50 Figment User's Guide The Story Editor Story logic is very intimately related to the Story Map. Figment sub-divides its rule base into local rule bases for every scene in the story (technically map block in the story). It makes a new local rule base every time you create a map block. (Careful - It also deletes it when you delete the map block.) Figment has one very special feature to its Story Map: you can re-visit old scenes and encounter new logic. You are not required to make your story do this, but you can do it. It is all in how you make your map. For purposes of this discussion, we will refer to any map that does not make new rule bases for old scenes as a simple map, and we will call a map that does make a new rule base for an old scene a complex map. 2. Editing Simple Maps To access the Story Map, move to the Top Level Editor and change the screen with the Up-Arrow key. The screen displays a matrix of scene blocks. Each block is numbered and titled with the name of a scene we want to use. Note that if none of the scene names repeat in the block titles, then it is a simple map. Under each block title name are the names of the titled scene's neighbors listed by the compass directions you would use to access the neighboring scene. We display the symbol "-*-" to mean that there is no neighboring scene in that direction. The player gets the message, "You can't go that way." when attempting to leave the scene in that direction. Note that you are not required to return by the same path that you arrived. In the real world, if Scene A is west of Scene B, then logically B is east of A. This law does not hold true for a fictional world; you can return to A from B by any direction you like. If B does not refer to A, then it is a one way street from A to B with no return to A. Story maps are easy to edit once you recognize that all you are doing is specifying the exits from a scene. The mechanics of editing are simple (since by now you are an experienced story editor): Page-Down from the Top-Level, Right-Arrow to the scene you want to change, Page-Down to the direction you want to change, scroll the scene names then Right-Arrow to another scene or Page-Up until you are back to the Top-Level. You can add or delete map blocks with the "+" and "Delete" keys. The new block is titled "Not Defined". When you create more map blocks than will fit on a screen, you see nothing happening, but 51 The Story Editor Figment User's Guide if you advance the cursor to the last block on the screen, Figment will begin scrolling blocks. Continue advancing until see your added blocks at the end of the list. The first block in the map is the entry scene for the story. Thereafter, there is no mandatory order. The first scene points to its neighbors who in turn point to their neighbors, etc. Thus the second block on the screen is not necessarily the second scene the player will see when playing the story. As you plan your map, remember that if during play you return to a scene you were in before, it will be in whatever condition you left it and its rule bases will also be in whatever state they were when you left (rules that switched off do not switch on again). 3. Complex Map Editing Complex maps are, naturally, harder. Remember we mentioned that the scenes are numbered in the map block titles? This is crucial to an understanding of complex maps. An example helps here. Retrieve our demo and bring the map up on the screen in the editor. We attempt to reproduce this here in our book, but it is better to see it in action. Using the first three blocks from that demo map as an example: 0 Mountains 1 Foggy Hollow 2 At the Beach N 1 Foggy Hollow 3 Dark Forest -*- N E -*- -*- -*- E W 4 Spooky Cave -*- -*- W S -*- 0 Mountains 1 Foggy Hollow S U -*- -*- -*- U D 2 At the Beach -*- -*- D This seems straightforward. If we leave scene zero, the Mountain scene, going north we arrive at scene 1, the Hollow. Continuing northward from there, we end up at scene 3, the Dark Forest. What happens if we change the title of block 3 from Dark Forest to Mountains? Do this now by scrolling the name using your cursor control keys. Now in block 1, the record has changed to indicate the mountain scene is simultaneously to the north and the south of the Hollow. But note that the numbers are different. Now imagine that we travel this new path we have just made. If we go south from the Hollow, we return to block zero, the Mountain scene as we left it and with the rule bases as we left them. If we go north from the Hollow, we enter the same Mountain 52 Figment User's Guide The Story Editor scene (object) but a different set of local rules. Now assume you edit the block titled Hollow. Position your cursor to the North direction record. You find as you scroll the scene names that you get two references to the scene named "Mountains". You get "0 Mountains" and "3 Mountains". Which one do you want? Your choice would be based on which rule base you want. Thus it is important to note the numbers next to the scene names and make sure as you design your map that you are pointing to the scene the way that you want to. By now you recognize that you are not specifying scene names in map blocks, you are specifying other map blocks which happened to be titled with the scene names. Map blocks do not really have names, just numbers. 53 The Story Editor Figment User's Guide K. Story Rules (Logic Programming) Rules form the logic that drives your story, and they are undoubtedly the hardest part of Figment for new users. Figment can function with absolutely no rules - but it is very dull. The more rules you can add, the more interesting your story will be. In other words, you have to achieve critical mass. It is very easy to get in over your head with rule bases. Initial efforts seem to go well enough, but you soon reach a point where doubling the size of the rule base more than quadruples the complexity. Do not try to fight this phenomenon; it is one of those immutable facts of life. Our advice, when that happens, is to split the scene into two, smaller, simpler scenes. Assume one case where you put thirty rules into one scene and another case where you put three rules into ten scenes. In terms of story development, your story has grown by the same quantity in both cases, but the work will be much easier in the second case. We say this because beginners tend to overwork the first scene and become disillusioned when they "hit the wall". You have to work up to it gradually if you want to scale the wall. This is why we tell you to make several scenes and a map before you write rules. 1. Theory of Operation A rule specifies actions to take in the event of certain conditions. In many cases, the action is simply to print a message in response to the operator's command creating the illusion of a dialogue. The "conditions" might be a certain player action or the state of the many object attributes and associations. If the conditions hold true, the rule is said to "fire", meaning its specified actions are performed. The collection of all rules is called the Story Logic. Figment divides the logic four ways into global and local logic and pre-command and post-command logic. Pre-command logic is concerned with a specific action. Post-command logic is concerned with the effects of any action. This allows you to make a "logic sandwich" that surrounds any action: >Take the Booby Trap [test for "take" and locked Booby Trap] It doesn't look safe to me, but ok if you say so. [command proceeds] You take the Booby Trap. [test for possession of locked Booby Trap 54 Figment User's Guide The Story Editor then kill player and print message] Some people go out with a bang. Others go out with a wimper. Lucky you. You get to do both! Global logic applies to all scenes. Local logic applies only to the scene for which it was written. Global and local logic are identical in nature, but global logic is stored separately and used repeatedly in every scene. Usually you write all logic for the local scene. When you find you want to use the same rule in a different scene, you move it to the global storage area with cut and paste operations. Rules governing the behavior of objects of type "Thing" are good candidates for global rules because the player can carry them from scene to scene. The logic is organized into sequences of rules called rule bases. There are four rule bases that apply when processing any comand: Global Pre-Command Rule Base Local Pre-Command Rule Base Global Post-Command Rule Base Local Post-Command Rule Base The primary reason for the organization is to improve the performance, but it has the added effect of cataloging the rules so you can find them easier, which is always good to do. We will ignore global logic now since the important distinction is between the pre- and post-command rules. When a command is given during play, Figment will process the command sufficiently to ensure the arguments are legal and that the command syntax is correct. Any mistake here will stop the processing and yield some generic error message. This means that none of your logic will be triggered by ordinary operator errors. This error-check ensures that the command will complete successfully unless you have written some intervening logic. Some common operator errors: >take the book You already have it. >take the ball There is no ball here. >drop the rock You don't have a rock. Once a command is determined to be legal, Figment interrupts command processing and checks every rule in the Global and Local Pre-Command Rule Bases to see if there is a rule for this command 55 The Story Editor Figment User's Guide action. There may be several such rules or there may be none. Any rules for this command are evaluated to see if their conditions hold true. If they hold true, the rule fires and its Command Flag is returned which enables or disables continued command processing. Rule processing continues until all rules that apply have been processed. Figment returns from rule processing to complete the command execution. It is at this point that the normal command action takes place if the command has not been disabled by a rule. Summarizing: All Global and Local Pre-Command Rules are checked on every command to find applicable rules. All applicable rules for the action are evaluated. (We do not quit early if a rule inhibits the command.) Rules that fire return a flag to indicate whether command processing should continue. A single negative flag will stop the command processing. We know the command will complete, because it was pre-checked so Figment only needs permission from your rules to proceed. After all this, the Post-Command rules seem anti-climatic. They just test for changes in state meaning links or attributes which changed since the last command completed. From all of the above, you should recognize that all Global Pre- Command Rules are processed on each and every command regardless of the scene making it the most-used rule base while the Local Post Command Rules are processed only on a successful command in the current scene making them the least-used rule bases. Minimizing global pre-command rules and maximizing local post- command rules improves performance and makes debugging your story easier - if Figment ignores a rule base so can you. Figment will ignore the post-command rule bases entirely until a command completes successfully. Most beginners over-use the pre-command rule bases. This is bad for several reasons: performance suffers, capacity in rule bases is finite, and the rules are too action-specific. Probably half of these rules could be re-written as Post-Command rules creating a better balanced, better performing story that is more user- tolerant. Observe. A pre-command rule is concerned with an action. A post-command rule is concerned with the result of an action. Many times it is just the result you want. Imagine the object of a scene is to 56 Figment User's Guide The Story Editor obtain a bank loan. Bankers only need to see sufficient funds to repay a loan, and there are many ways to achieve that. You would have to write many pre-command rules to consider them all, but you only need to test a user-defined attribute for "Net Worth" or "Cash Flow" with a post-command rule to satisfy a banker. Most interactive fiction hinges around the player making the correct actions. This is often unavoidable, but the price is that many stories are stuck until the player discovers the right move. It also does not tolerate the player's innovations. They often can think of things you did not. You can avoid this by re- phrasing the rule as a post-command rule and creating some literary device waiting in reserve that creates the right conditions if the player takes too long to perform the right action. This is really the best of both worlds because it tolerates beginners without penalizing experts. 2. Anatomy of a Rule It's time to study the rule itself. Post-Command rules are slightly simpler so go to the Top Level Editor and set the screen to display the Post-Command Rule Base and follow along with the discussion. Page-down and you can scroll the rule number to see the different rules in the rule base. A rule has three major parts: a conditional clause (the "IF" part), an executional clause (the "THEN" part) and up to sixteen messages that can be printed. The conditional clause has up to eight expressions (typically tests of links and flags), all of which must hold true in order to fire the executional clause. The executional clause can perform up to eight operations each time the rule fires. You can specify three types of rules: IF, WHILE and FOR. Page- down from the rule number level. Your cursor lands on the rule type. These types scroll under the cursor when you hit the Up- Arrow key. The IF-type rule will fire only once. It then switches itself OFF and is never processed again for the remainder of the story. To the right of the rule number, you see an indicator which reads "Switched: ON (or OFF)". You can reset this manually if you like. Usually you check this indicator when debugging to see if the rule fired. A WHILE-type rule is an IF-type rule that never switches off. It will always fire when its conditions hold true. The indicator should always read "ON" for a WHILE clause. (It might not if you have recently changed the type and forgotten to switch it back ON 57 The Story Editor Figment User's Guide so get in the habit of checking.) The FOR-type rule is very powerful (read tricky). It is used for stunts. A counter tracks the number of times that the conditions have held true. You specify the start and stop counts when you want the rule to fire. If you specify the start count to be 3 for example, then nothing happens the first two times the conditions are true. You can also specify a step count which causes the rule to fire every second or third time and so forth. This can be used to make messages appear at intervals. The indicator will show the rule has switched OFF when it reaches its specified stop count. The processor checks each rule but skips to the next rule when it sees the rule has been switched off. Rules should always be switched on at the start of play for the scene. You may, however, want to switch off some rules in order to debug others. The switch also functions as a "soft delete". You can keep an obsolete rule switched off and switch it on later if you decide to keep it. There is no way to switch a rule on during play once it is switched off. You can, however, simulate that effect by testing a lock flag and having another rule change that lock flag. Thus a rule can appear to be asleep until the lock flag changes. There are many examples of this in the demo. The Conditional Clause, the Executional Clause and the Messages represent separate editing levels that you enter with Page Down. The rule editing screen is the most dynamic editing screen. The rule expands and shrinks as you add and delete expressions and messages. The expressions themselves also expand and shrink as you change their functions, arguments, and modifiers. You often cannot display all the messages at once so you see a rolling window of messages as you step through the message list. All of the conditional expressions must hold true for the rule to fire. Experienced users will recognize this as a "Logical AND" and immediately ask where is the "Logical OR"? The answer is that each rule in the rule base is logically OR'd meaning that Rule A fires, OR Rule B, OR Rule C, etc. So if you want to OR an expression, copy the rule and change the conditional expressions. This sounds wasteful, but in practice if you change the conditions, you probably will change the executional expressions or the messages too which means you need a new rule anyway. 3. Expressions This is an overview of expressions and their editing. We will cover expression editing in full detail later. 58 Figment User's Guide The Story Editor We call each line of the conditional or executional clause an expression. An expression is composed of a function, objects that act as arguments to the function, and modifiers. For example: While { Player is linked to Ball by Ownership }... This expression asks "Does the Player own the ball?" (as opposed to merely having it in his or her possession.) The conditional function in this example is "is_linked_to". Its arguments are Player and Ball, and the term "by Ownership" acts as a modifier. Figment will check to see if there is a link with the label "Ownership" in the Player's link list. If there is, the rule fires. The syntax reference (see Conditional Function Reference, later) indicates that the modifiers for "is_linked" are optional. That means if you scroll them far enough, they blank out. This yields the expression: "Player is linked to Ball". Figment would then return "true" if it found any link to the ball in the Player's link list regardless of type or value. We change each portion of an expression by scrolling. Try it. Advance the cursor from the rule type to the first expression and hit Page-down. The rule type lights in reverse video to signify expression editing has been initiated. Your cursor lands on the expression's function. Scroll the functions and stop at the function you want to use. Notice the entire expression can change depending on the function. Some functions need three arguments while others need only one, some have modifiers, etc. When you have decided on the function move the cursor left or right to set the arguments and the modifiers. We will cover the rule editing in detail later. You are not required to write any conditional expressions at all if you do not want to. An empty conditional clause means the rule is always true, and it fires every time the player successfully completes a command. Pre-command rules, by the way, cannot have empty conditional clauses, because they test for action so you would be testing for no action which means it would become a Post-command rule. (When you want a Pre-Command rule to fire on any command, you can negate the User-defined Command Parser.) Neither are you required to write any executional clause at all. Often you need only the message since it prints to the command 59 The Story Editor Figment User's Guide window automatically so it is not unusual to see an empty executional clause. 4. Messages Interactive fiction requires delivering an appropriate message in response to a player's actions so shipping text strings to various destinations is an important activity for executional functions. Most rules are used primarily to hold messages for delivery at the appropriate time. The text that you defined for your objects merely represents the initial condition. Your rules will alter it during play by copying messages to the description and examination strings. When the rule fires, its Current Message is printed automatically to the Command Window where it appears as though in response to the player's command. You can switch the automatic printing off when you want the message copied to a different destination. For example, the message can be copied to an object's Long Description which will cause the story's Scene Description to change. The rule reports its Current Message number at the end of the line titled "Messages". Usually this begins as message number one. The Current Message number does not change unless you change it with the executional function "inc_message" which increments the current message number. This can be used to change the message for the next time the rule fires or for copying multiple messages to multiple destinations. For example: While { Player is linked to Ball } Then { inc_message } Messages: 4 total Switched On Current Msg: 1 1. Hey that's a neat ball. 2. It's not yours. You better not keep it. 3. I think it belongs to someone else. 4. You're going to get in trouble. This rule prompts a warning message to the command line each time the player completes a command as long as the player has the object named Ball. With each move the message gets progressively ominous, because the Current Message pointer is incremented each time the rule fires. Eventually the last message is encountered. The inc_message function cannot increment past the last message so this rule will continue prompting the last message each time a command completes, meaning the system will nag ad nauseum until you drop the ball. Some people won't want the nagging message 60 Figment User's Guide The Story Editor that keeps prompting. In which case, change the rule type to "For 1 to 4 step 1". Now the rule shuts down after it reaches the fourth message. An executional function, "on_skill", is also provided that allows you to deliver the appropriate message relative to the player's skill level so you can even tailor your work to beginners or experts. There are five skill levels so on-skill chooses one message from a block of five. You can have up to 16 messages and combine "inc_message" with "on_skill" to increment to the next block of five messages. This can yield a progression of three messages chosen according to the player's skill. Often you do not want the message to be printed automatically. You can suppress the automatic printing with the ON/OFF switch on the Messages line so you can copy messages to object descriptions and examination messages without printing them to the command window. 5. A Rule Base in Action An example from the demo serves to illustrate a sequence of rules in action. These rules are all post-command rules meaning that the player must complete a move each time the rule is to be processed for possible firing. In other words, we have programmed a mini-drama to unfold while the player is fiddling with other things. The entire sequence discussed here takes a total of 9 moves to complete. We add the character "Rushin' Bear" to the scene. We want to put messages to its description message, but we will clobber the existing message before it is displayed (Relatively harmless, but wasteful), so we delay the message transfer one move with a FOR clause that begins on the second move after the bear is added to the scene: FOR 2 to 5 step 1 { <scene> is linked to Rushin' Bear } THEN { copy msg to Rushin' Bear's Long Description inc_msg } Message 4 Total Switched OFF < 4 messages > By delaying the start of message transfer to the second move after the bear arrives, we allow the object's original description to be displayed, then we copy a message in its place and increment this rule's message pointer to this rule's second message. Process repeats three more times. The result is that 61 The Story Editor Figment User's Guide we announce the bear's pending arrival with a sequence of increasingly ominous messages. Once done, we want the bear to initiate a fight so we unlock the bear after the fifth move: FOR 5 to 5 Step 1 { * the scene * is linked to Rushin' Bear } THEN { unlock Rushin' Bear } Message 0 Total Switched OFF < no messages> This functions exactly like an IF statement, but it is delayed 5 counts. We then follow with a third rule (not shown here), a 4- count FOR statement that tests the Bear's lock flag and unleashes a barrage of punishment forcing the player to fight the bear or die. The entire Bear sequence was triggered by the player's action. (Extra Credit: Study the listing in the demo. Can you find the event that brought the Bear? Wasn't that easy?) This sequence of only three rules has driven a little mini-drama in the scene. There can be many such dramas contained within the rule bases, all of which progress one notch with each command. The player only sees the Scene Description change and the command responses appear after typing a command. The impression is as though the different dramas played out in the scene are progressing in parallel. L. Editing Rule Bases Once you have practiced editing objects (stuff and scenes), rule editing should come as no great difficulty. They are, by their nature, more complex than objects so there is a greater amount of work here. By now you should recognize that if what you want to edit is not accessible with the Right-Arrow key, it is on a level lower and that the Page-Down key will reach that level. You should also recognize that the editor will show you what you can edit on this level by holding the Right- or Left-Arrow down and watching where the cursor flies. Also the Home key is used extensively in expression editing to give you more options. 1. Rule Base Editing 62 Figment User's Guide The Story Editor From the Top Level Editor, select the appropriate screen editor for Pre- or Post-Command Rule Base editing. Hit Page-Down. Your cursor lands at the rule number. We call this the Rule Base Level, because you are addressing the rule base as a whole, not elements of the rule (Yes, the rule's switches are at this level for convenience). You can display the different rules in the rule base by scrolling the rule number. The label, "Rule #1 of 10" means there are ten rules in this rule base and you are viewing the first one. You can also delete, insert, cut or paste a rule at this point. Moving left, you can change the scene by scrolling the scene name to access the different rule bases for each scene of the story or the global rule bases. Moving right, you can change the switches for the particular rule currently displayed. Page-Up from this level returns you to the Top-Level Editor, also Escape. a. Adding/Deleting Rules Rules can be added or deleted with the "+" and "Delete" keys respectively. Try adding a new rule now and note that the rule count changes. The new rule has been added to the end of the rule list and the screen now displays the new rule. You are probably wondering why the screen display did not change. The reason is that the "+" function is actually a copy function too. It made a copy of the rule you were viewing when you hit the "+" key and displayed the copy, changing only the rule number. Often you want to make a rule very similar to a rule you already have. Display this rule with the Up-Arrow key then hit "+". The new rule copy is added to the end of the list. Now edit the new rule to adapt it to your needs. Note that this can also be used for re-ordering the rule sequence by copying rules to the end of the list with the "+" key then deleting the originals with the "Delete" key. The order of rules can be important when rules are dependent on each other. A better way to change the order of the rule sequence is to use cut and paste operations. To delete a rule, scroll the rule number until you are displaying the rule you want to delete. Hit the button labeled "Delete" on your keyboard. There are no contingencies to be concerned with as with object deletion. Only the deleted rule is affected. 63 The Story Editor Figment User's Guide b. Inserting Rules You can insert an empty rule anywhere in the sequence. Scroll up the rule number until you are viewing the point where you want to insert a new rule. Hit the key labeled "Insert" on your keyboard. The rule you are viewing and the following rules will be moved back in the sequence one position and you will be viewing a new rule you can edit. c. Cutting Rules - F7 The "cut" function is especially useful for moving rules within the sequence and between different rule bases. There is no difference between local and global rule bases, and you can move rules freely from one to the other. There are subtle differences between pre- and post-command rules, but the paste function will let you paste the wrong type, and you are expected to correct the differences (the first expression, and the enable switch). To cut a rule, simply scroll the rule number until you are displaying the rule you want to cut and hit the F7 key. The rule is removed from the sequence and held for a later paste operation. Repeated strikes on F7 is comparable to Delete. Each time you cut a rule, the last rule in the cut buffer is over-written with only the final rule cut being saved for pasting. d. Pasting Rules - Shift-F7, Alt-F7 The "paste" function presumes you have cut a rule prior to the paste operation, and it will beep if there has been no rule cut prior to the paste operation. If you are not sure what rule is in the cut buffer, paste it anyway. You can delete it or cut it out again with a single keystroke so no harm done. To paste a rule, scroll the rule numbers until you arrive at the point in the sequence where you want to insert the rule. Hit Alt-F7 to paste the rule before this rule or Shift-F7 to paste after this rule. In either case, you will end up displaying the newly pasted rule. If you want to paste a rule to the first position in a sequence, display rule number one and hit Alt-F7. If you want to tack a rule onto the end of the sequence, display the last rule and hit Shift-F7. Repeated pastes will insert repeated copies into the rule base. 64 Figment User's Guide The Story Editor e. Changing Scenes (and Rule Bases) in the Editor To the left of the rule number is the scene name. This indicates you are looking at the local rule base for the scene (Map Block actually) in question. Move the cursor over the name and scroll the name. You have changed the display to display the local rule bases for a different scene in your map. You should recognize that they change in the order in which they are specified in your map (not the order in which the scenes are listed in the Scene Editor). Every Map Block gets its own pair of rule bases. When you enter the editor, you are looking at the rule bases for the current scene (Map Block) in the story, but you can change the scene here and study other rule bases. Note that this changes the scene for the story as well. If you hit F1, you find yourself viewing the story in a different scene. The Shift-F3 (write-all) function in the Top Level Editor is designed to reset the story to the starting scene. Usually you hit this routinely on your way out of the editor so any scene changes here are harmless. Sometimes, you are just poking around and do not want to save your changes so remember to put the scene back before you leave the editor. The scene change function will not work if you have not made a map. This discussion assumes you are working on an existing story which has a map defined. If you are working on a new story, you are stuck in scene zero until you define the map. See the section on map editing for further details. A word of caution. Note that there is a number beside the scene name. This is the number of the map block, since as we mentioned, it is the map block that you are changing. See the section on the Map Editor for full details of Map Blocks. Remember we mentioned that sometimes you re-use scenes with different logic by creating different map blocks titled with the same scene. The number tells them apart. f. Global Rule Bases Global rule bases appear in every way identical to the local rule bases. To access them for editing, simply move the cursor over the scene name and scroll up or down until the name "Pre-global" or "Post-global" appears. Add and edit the rules as you would edit any sequence. Be sure to re-set the scene name if you are returning to the Presentation Environment. 65 The Story Editor Figment User's Guide g. Rule ON/OFF Switch Also at this level is the aforementioned switch to turn off the rule. Many rules switch off during the course of play. You can manually toggle this switch by advancing over to this item and scrolling this flag. Continue advancing and the cursor wraps back around to the scene name and the rule number. h. Listing Rule Bases The F4 key will write the full rule base (either Pre- or Post-, not both) for the current scene to a disk file where you can read it at your leisure. The F4 key is enabled in the Top Level Editor when the screen is displaying either the Pre- or the Post- Command rule editor. Page up to the top line on the screen and hit F4. You just made a listing file on your disk with the same name as the story but with a ".LST" file extension. Every time you hit F4, the previous contents of this file are deleted and replaced with the new listing. You can exit with F10 to read this file with the DOS command "type" or print it on your printer with the DOS "print" command. If you change the screen (or change the scene) to display a different rule base, then hit F4 again, the same disk file will be re-used and your last listing will be lost. (Call it a "losting".) Shift-F4 generates a listing file for all the rule bases for every map block, in effect, a full logic dump. Take care. This can generate a file 60% as large as the original story file. If you are tight on disk space, you may want to swap diskettes before hitting Shift-F4. Again, this over-writes any existing listing file. Listings are fully expendable, feel free to delete them when you need to recover disk space. The file is automatically created when you hit F4 if the file does not already exist. Note. DOS installs a print driver routine the first time you give the print command after booting up. This routine is then left in memory waiting for any subsequent print requests. If you have not printed anything before you start Figment, and you use F10 to visit DOS and do your printing, you will install this print driver at a memory location above the last memory address that Figment consumes. Eventually, you return to Figment and quit completely to run another DOS application. If this program consumes more memory than Figment did, it runs afoul of the print 66 Figment User's Guide The Story Editor driver sitting in an unusually high location in memory, and you get the alarming message: Insufficient memory to execute program. The only way to kill this print driver is to re-boot your machine. Hit reset. To avoid this problem, load the print driver first by giving the print command with no filename. This loads the driver and reports to you that the print queue is empty. Now start Figment. If you use this feature often, you may want to create a batch file so you will not forget. 2. Rule Level Editing Hit Page-Down from the Rule Base Level Editor and your cursor lands at the Rule Type. Advance the cursor and it moves sequentially to the Conditional Expressions, the Executional Expressions and the Messages where it wraps back to the rule type. These are separate editing levels, and you can access them by hitting Page-Down when the cursor is at these locations. Page-Up/Escape returns to the Rule Base Level Editor. a. Rule Type You can scroll the rule type. Notice the start, stop, and step counts magically appear and disappear when you set the rule type to FOR. Notice if a rule is switched OFF that changing the type does not automatically switch it ON. You must do this manually. b. Expression Editing Expression level editing is very similar for both the conditional and executional clauses so we will describe both processes simultaneously. There is only a slight variation in format between the two expression types. When you enter expression level editing with Page-Down, the rule's type statement or the word "Then" lights up in reverse video to indicate the expression level editor is enabled. If you do not see this light, you cannot edit the expressions. Figment will only beep as you attempt to scroll values. Continue hitting Page-Down to move down to the expression you want to change. Page-Down also automatically adds new 67 The Story Editor Figment User's Guide expressions for you when you hit the end of the list up to a maximum of eight expressions per clause. It then moves down to the newly added expression. Page-Up moves up the list and finally exits the expression level editor whereupon the reverse video returns to normal signifying you have left expression editing. The "+" key automatically adds new expressions to the end of the list, but it does not move into them. The Delete key deletes the expression the cursor is on. The rule display automatically expands and contracts to accommodate newly added and deleted expressions. If the clause is empty, it reads "No Expressions", meaning you must add one. Otherwise Figment will beep when you attempt to edit nothing. As you make changes to the expressions, Figment re-computes the line length to accommodate the various options you have selected. The cursor centers on the function phrase or the function's argument phrases. It changes position slightly as you change these phrases. The cursor can only be an approximate guide to say that you are working on the function or its arguments. It cannot indicate all the possible options at each location. Experiment with the up/down arrow keys and the Home key to see what your choices are. (1) Setting the Function When you enter expression editing, your cursor lands on the expression's function. The editing operations that you can do on an expression depend on the function so this will be your first task. Set the function you want by scrolling the function names with the Up-Arrow key. You can negate conditional expressions by hitting the Home key when the cursor is on a function. The Home key is very powerful, but here it only serves to toggle negation on or off. (See data types below.) The editor will only scroll the functions that are legal for your context: conditional functions will only scroll in conditional expressions, executional functions in executional expressions and story commands in the first conditional expression of a pre- command rule. No system-level functions (restart, restore, save, toggle, etc.) will be seen in the expression editor meaning you 68 Figment User's Guide The Story Editor are not allowed to write rules to inhibit or restrain them. (2) Expression Argument Counts The editor varies the expression argument count according to the function. Some functions require no arguments while some allow several. As you advance the cursor with the right-arrow key, the cursor skips over each argument position and eventually wraps back to the beginning of the expression when the maximum allowable argument is passed. Thus as you change the function, the cursor will make shorter or longer laps as you cycle it left and right. Some functions have different forms that use different numbers of arguments. For example, you can say: If { Player does take ball }... or If { Player does take ball from boy }... In such a case if you choose not to use the last argument, simply scroll up (or down) the last argument's name until it blanks out. The modifier will also disappear. (3) Data Types - The "Home" Key Each function specifies the legal data types for its arguments (see the Command Reference sections) so that the editor can inhibit mistakes before they occur. The "Home" key is used to access different data types for the function arguments. It also serves to negate conditional expressions when the cursor is positioned over the function. Some functions allow a wide variety of data types for the function arguments while others allow only one. You can check the syntax in the Command Reference sections that follow. You might find it easier just to try hitting the Home key. If nothing happens, the function allows no other options for data types at that location in the expression. For example, the function "is linked to" tests for a link from one object to another. When making links, you should recognize 69 The Story Editor Figment User's Guide that scenes can have links to objects, but objects cannot have links to scenes. The reason is that links imply "possession" or similar association. Scenes have objects in them, but objects do not have scenes in them. Neither can scenes be linked to other scenes. Thus the "is linked to" function specifies its arguments as follows: <stuff or scene> is linked to <stuff> If you strike the Home key when the cursor is positioned over the first argument, you can change to scrolling scene names from scrolling stuff names. Another strike on the Home key, and you are back to scrolling stuff names. Scrolling, as always, is done with the up/down arrow keys. The significance of this is that you can access any scene name in many functions, but only where it is legal to do so. For example, you might want to specify scene names or directions when testing the "go" command: If { Player does go North }... or If { Player does go to Basement }... (4) Arguments Specified by Attributes Some functions allow their arguments to be specified by the attributes Type and Sub-type. For example: If { Player is linked to obj sub-type Money }... This would be read as: "If the player is linked to an object of sub-type 'Money'..." meaning "Does the player have something of value?". To access the attributes, simply hit the Home key when the cursor is positioned over the second object until you see the sub-type attributes. Scroll the sub-type names until you see the one you want. When this expression is processed, Figment will search the 70 Figment User's Guide The Story Editor Player's possessions until it finds the first object that qualifies. It then stores this object's name (see pronouns below) for future use and reports true. The syntax guide for the function lists which functions use this feature. (5) Pronouns Whenever you specify arguments to functions indirectly, for example by their attributes, you create a separate problem. How do you refer to them later? Figment supports some special pronouns for that purpose. For example: If { Player is linked to obj sub-type Money } Then { Take * the object * from Player }... We display the pronoun "the object" between asterisks to remind you that this is a pronoun. Pronouns remain defined until they are re-defined by any function that allows indirect argument references. This allows pronouns assigned in conditional clauses to be used in executional clauses. It is not wise nor recommended to stretch your luck and try to carry over pronouns between different rules, but some may try. In the right circumstances, it would work. Notice that in the example above, the "take" function in no way changes the definition of the pronoun. It merely uses it. The function "is linked to" assigns the pronoun, and only when it finds an object of sub-type "Money" in the player's possession. Note also that "is linked to" only assigns pronouns when an indirect argument reference is used. When object names are used directly, the existing pronoun assignment remains unchanged: If { Player is linked to Wallet } Then {... No need for a pronoun in this example. We know exactly which object is being referred to so the pronoun "the object" remains unaffected. Conditional functions might assign pronouns for any of their three possible arguments. When they assign a pronoun, the 71 The Story Editor Figment User's Guide following convention applies: An indirect reference in the first argument is assigned to the pronoun "the subject". The second argument assigns to the pronoun called "the object" The third argument assigns to the pronoun called "the 2nd object". Executional functions are commands that use an implicit subject: (you, Figment) take object from object An indirect reference in an executional function would not assign to the pronoun "the subject" since subjects are not used, but its first and second arguments would assign to "the object" and "the 2nd object" respectively. Thus: ...} Then { Take obj sub-type Money from Player Add * the object * to Bank }... (6) Cutting and Pasting Expressions You can cut an expression out of the clause by hitting F7. The cursor location does not matter. It can be anywhere on the expression. The expression can then be pasted back with Alt-F7 or Shift-F7 as described above for rules. When you paste an expression of the wrong type in a clause, Figment quickly converts the function in the newly copied expression to the appropriate type. Figment is in effect politely telling you that you will have to re-state the expression anyway. Net effect, pasting will not look much different from inserting for the majority of cases. (7) Inserting Expressions The Insert key will insert a new expression in the clause at the cursor location. The existing expressions are bumped back to open the gap in the sequence for the new expression. Note when inserting a new first expression to a pre-command rule's conditional clause, the old expression moves back and is transformed to an ordinary conditional expression. 72 Figment User's Guide The Story Editor 3. Message Editing Message editing is accessed via Page-Down when the cursor is positioned over the word "Message" on the screen. The word "Message" lights up in reverse video when you enter the message editing level, and the cursor jumps to the message switch. Set the message display switch to "off" or "on" by scrolling up with the Up-arrow key. Advance to the "Current Msg:" position with the Right-arrow key. The Current Message refers to the message that will be passed or displayed the next time the rule uses its messages. The executional function "inc_message", for example, will advance the Current Message pointer so that the next message can be passed. If you have been playing the story before entering the editor, you might see it pointing to some value other than 1. You would set the Current Message value whenever you use a function like the user-defined command parser ("say_cmnd") that uses the first rule message by default. Otherwise, you probably do not have to change this value. Advancing one more position (or hitting Page-Down) puts you in position for editing the rule messages. Page-Up/Down moves you to the appropriate message for editing. You cannot edit a message where none exists so hit "+" or Page-Down when there are no messages so that you have a message to edit. Note that the message total shown on the screen updates as you add and delete messages. If it reports zero messages, you cannot edit a message until you add one. Page-Up/Down behaves in a similar fashion as for expression editing so do "+" and Delete. Note that when screen space is limited, the messages will roll up/down in a window as required to fit the available space. The F7 key will cut the message to the text buffer from which it can be pasted back (wherever text is needed: rule messages, object names, descriptions, etc.). Pasting behaves slightly different for rule messages than it does for object text strings. The message the screen cursor points to is not replaced by the text in the cut buffer. Instead, the cut buffer is inserted as a message in the list of rule messages. Alt-F7 and Shift-F7 behave as they do in expression editing, and repeated paste operations will generate repeated copies. The message itself is edited in the normal manner for all text. When the cursor is positioned at the start of the message, you 73 The Story Editor Figment User's Guide can type in replacement text directly or you can hit "F6" and use the full-screen text editor to modify existing text. Page-Up exits the message editing level and returns to the rule editing level. When the list of messages is long, Escape is easier. Be sure to leave the rule's current message indicator reading the message number you want. Typically this is the first message, but you can skip messages if you want. That is all there is to editing rules. You can exit with Page- Up. We now discuss the distinction between Pre- and Post-Command Rule Bases and then discuss the various rule functions in detail. M. Pre-Command Rules Often you want to intercept or block a command from executing. Pre-Command rules allow you to do that. Change the screen now so you can study the Pre-Command Rule Editor. It is very similar to the Post-Command Rule Editor, by deliberate design so that you will have less editing to learn. The major distinctions are the addition of the "Command" switch in the upper right corner of the screen and the first conditional expression. The Pre-Command rule differs from its Post-Command counterpart in that its first conditional expression tests for the verb in the player's command. This expression is phrased as, "If {player does [not] <verb>}". The remaining expressions, if any, test state variables as the Post-Command rule does. The Pre-Command Rule has the option of enabling the command (allowing it to proceed) or disabling it (blocking command completion). A blocked command is a failed command, and the Post-Command rules are not processed. Pre- and Post- rules are often used in combination. A rule in the Pre-Command Rule Base performs operations that in turn trigger a rule in the Post- Command Rule Base. Pre-Command rules are rules tagged for a specific function. Some functions turn this around and deliberately use them as a source of user-defined messages. (See Fight, Shoot, Hit, Charm) The User-Defined Command Parser is implemented as a Pre-Command Rule, but this is the subject of an entire section of this book by itself. 74 Figment User's Guide The Story Editor 1. Modifiers in Pre-command Rule Expressions We have seen conditional expressions with modifiers, and we have seen how we can use them or omit them in our expressions when we want to be specific or general. Many story commands have modifiers too, and you have the option of testing for these modifiers or ignoring them. When you ignore the modifier, you create a broader test case, and when you include the modifier you create a more specific test. For example, the expression: If { Player does give bat }... does not care to whom the player gives the bat, while the following expression does: If { Player does give bat to Boy }... Only a few commands use modifiers, but they are critical commands: take - from give - to put - in put - on shoot - with Modifiers are associated with the last argument in the expression. If you have blanked this argument, then you will not see the modifier either. Scroll the argument until you see the object name you want. The modifier will appear along with the argument name. Figment will set a default modifier commonly used with the chosen function. Where the function allows more than one modifier (e.g. put), you can change the modifier by hitting the Home key and scrolling the modifier names. Hit the Home key again and you are back to scrolling object names. 2. Directions in Pre-Command Rules You can test for specific directions in the "go" command. The same philosophy applies as described above for modifiers. If you do not specify a direction, then the rule will fire regardless of which direction the player goes. 75 The Story Editor Figment User's Guide 3. Negating Pre-Command Rules Negation is allowed for Pre-Command Rule expressions. The first conditional expression in a pre-command rule is phrased as, "If { Player does (command)...}" or "If { Player does not (command)...}". The form changes when you hit the "Home" key. A negated command rule simply means that the rule will fire on any command unless the player gives this command. In fact a negated "while" rule will fire every time until the player gives the specified command. This can be very tedious if the same message repeats continuously so such a rule would probably include extra conditional expressions to narrow the possibilities of its firing. Some functions have alternate forms and the rule can be very specific. Consider the case where the test is: If { Player does not take Ball }... and the player says "take the ball from the boy". In this case, the player did not say "take the ball" exactly so the rule would fire. 76 Figment User's Guide The Story Editor N. Conditional Function Reference This section describes the Conditional functions you can use in your rules. The next section describes the Executional functions. Conditional functions are used in the conditional part of a rule. They are phrased slightly different from the executional functions in order to achieve a more natural style. If { Player is linked to Ball } Then {... seems more natural than perhaps: If { is linked Player Ball } Then {... Meanwhile, Executional functions are used in the command sense. ...} Then { link Romeo to Juliet by Romance > 30 copy msg to Romeo's Long Description }... 1. Does_Action Syntax <Character> does [not] <action> This is the primary conditional function for pre-command rules. You only see this function when you are editing the first expression of a pre-command rule. The character can be any character including the Player and the Actor. The action is any legal command from the Presentation Environment, but you will not find system-level commands like "restore" or "restart" here. The syntax for the action follows the command syntax in the Presentation Environment. Only rarely is there a special option. For example: If { Actor does go anywhere } Then ... You will not find the direction "anywhere" in the "go" command syntax. It is a special implementation so you can write rules to inhibit all exits from the scene. 77 The Story Editor Figment User's Guide 2. Fit_Profile Syntax <object> does [not] fit profile of <profile label> Compares a set of the object's attributes to a weighted decision matrix of attributes. See Profiles. 3. Have_Attribute Syntax <object> does [not] have attribute <attr label> [<>= value] <pronoun> Tests the object for the specific user-defined attribute. A value can be specified to determine if the attribute value is less than, greater than, or equal to the specified value. If { Actor does have attribute Wisdom > 12 }... Hit the Home key when the cursor is positioned near the math symbols to change them. You can blank the value entirely meaning you are only concerned with the attribute and not its value. Hit the Home key until the value blanks out. 4. Is_dead Syntax: <character> is [not] dead Use this in conflicts to test for the defeat of characters. When an opponent dies in a conflict it is probably the Player that killed them. When Players die in a conflict, it is not clear who killed them since there can be multiple opponents. This will tell when the Player is dead, but it will not tell you who did the deed. There is also a special case where you want to use this function: If { Player is dead } Then { Kill Player } ... This seems especially vindictive, but Figment is always trying to 78 Figment User's Guide The Story Editor recuperate Players when their health is failing. If this healing process coincides with the death blow, Players appear to resurrect. This rule, however, seals their fate. It also gives you an opportunity for some parting words. It is probably wise to put such a rule in the Post-Command Rule Base for any scene where a conflict can occur. You can put it in the Global Post-Command Rule Base, but if you want customized messages for every situation, you will have to paste it into the local rule bases. 5. Is_linked_to Syntax <object> is [not] linked to <object> [by link-type] [<>=value] <pronoun> <obj type> <obj sub-type> <pronoun> <obj user-type> Looks for a reference to object-2 in object-1's link list. The type and value are optional. They are ignored if they are left blank. Some examples: If { Boy is linked to ball Romeo is linked to Juliet by Romance > 12 John is linked to Mary by Marriage John is linked to House by Mortgage > 100 }... Blank the value by hitting the Home key when the cursor is positioned near the value. The link type blanks when scrolled with the Up/Down-arrow keys to the end of the link type list. The different object types are accessed by hitting the Home key then scrolling to the desired item. You can test for links to object types or sub-types. For example: If { Player is linked to obj sub-type Money }... Read this as, "If the Player is linked to something whose sub- type attribute is 'Money'...", meaning, "Does the Player have 79 The Story Editor Figment User's Guide anything valuable?". This loads the pronoun "* the object *" with the name of the valuable object found, and you can use this pronoun in a later expression in the rule: If { Player is linked to obj sub-type Money } Then { take * the object * from Player }... Strike the Home key when the cursor is positioned over the second argument, and you can scroll type names. Strike Home again, and you can scroll sub-type names. Hit Home again, and you are back to scrolling stuff names again. Another example: If { Player does give Flowers to Juliet Player is linked to Juliet by Romance > 20 } Then { Link Juliet to Player with Romance 20 } Message 1 Total Switched: ON Current Msg: 1 1. Gosh, @Player, I didn't know you cared. 6. Is_locked Syntax: <object> is [not] locked This function tests the object's lock flag to see if it is ON, in which case, the function is said to be TRUE and the rule fires. If { Bear is not locked } Then { change Player's Health -2 } Message 1 Total Switched: ON 1. Boy these bears get mean when you chain 'em up don't they? 7. Is_open Syntax: <object> is [not] open This function tests the object's "open" flag similar to the lock flag. 80 Figment User's Guide The Story Editor 8. Is_type Syntax: <Stuff> is [not] <user type label> <Scene> <type attribute> <Pronoun> <sub type attribute> Used primarily to test for the presence of a user type label such as: If { Player is user type Lawyer }... The type and sub-type attributes are provided for completeness. There is no crying need for them, but they might be useful testing pronouns. 9. Is_wizard Syntax: <Player> is [not] wizard This function assumes you might want to take some special action on behalf of skilled players: If { Player is wizard } Then { unlock Door open Door } Message 1 Total Switched: ON 1. The Shaman knows a Wizard when he sees one and steps aside holding the door for you. 10. Probable_Event Syntax: <value>% [not] Probable Event This conditional function will generate a random action of your designation. The rule would look like: While { 15% Probable Event } Then { go_to_map_block 7 Over the Cliff } Messages 1 Total Switched: ON Current Msg: 1 1 A capricious wind blows you off the cliff. The percentage you specify determines the probability, hence the 81 The Story Editor Figment User's Guide name Probable Event. In this case, the player has a 15% probability of getting blown off the cliff each time the rule is checked. You may negate the function. Something that is 85% not probable is 15% probable. You can also just change the percentage and achieve the same effect. This rule will drive you bats during debugging or demonstrating your story even if you specify the starting seed for the random number generator. You may have to switch the rule off manually in the editor. 11. Say_cmnd (User-Defined Command Parser) Syntax: Player does [not] say cmnd This is the User-Defined Command Parser. It is only used in Pre- Command rules. The function uses the first message in the rule as a specification of word groups and the Boolean operations that should be performed to form a sentence from the word groups. Punctuation should not be used. Differences in upper or lower case letters is ignored. Rule messages can be up to 2K bytes, but command sentences cannot exceed 80 characters. Example: If { Actor does say cmnd <other conditions go here> } Then { unlock door open door copy msg to Door's Long Desc. inc_msg copy msg to Door's Brief Desc. } Message 1 Total Switched: On Current Msg: 2 1. (Abracadabra or Shazam or Hocus Pocus) 2. With a rumbling groan, the mighty stone door swings open. 3. The door stands open before you. A simple example like this could probably be solved with synonyms, but not as well. Synonyms are global and act as extra handles for grabbing built-in functions. In this case if synonyms were used, people would be using magic words to open doors, windows, boxes,... everything. User-defined commands can be local to specific situations within a scene so that you can write unique rules. 82 Figment User's Guide The Story Editor Only the first message is tested. The remainder are left for your use. This makes this rule form unique in that you probably want to leave the message pointer set to the second message and not, as is usual, pointing to the first message. If you left the rule pointing to message number one, the effect would be as though the command phrase were being echoed back to the player. More discussion on Synonyms and the User-Defined Command Parser can be found in Part III. 83 The Story Editor Figment User's Guide O. Executional Function Reference The executional functions are used in the second part of the rule. You can see these functions when you scroll them in the editor. 1. Assign_User_Type Syntax: Assign <label> to <stuff> <scene> <pronoun> Adds the user-defined object type label to the object if the object does not already have the label. See also "Remove User Type". 2. Change Syntax: Change <object>'s <attribute> <value> Changes an object's attribute by the specified value. If the value is negative, this is equivalent to subtracting the value. Attributes are signed 8 bit quantities, meaning they can hold numbers from -128 to +127. Normally in computer math if you add too much to a positive integer, you "overflow" and get a negative number. That is, 126 + 2 = -128 in 8 bit integer math. Figment prevents overflow; it just stops when it reaches the limit so with the change function, 126 + 2 = 127. While { Player is linked to Pharoah's Curse } Then { Change Player's Health -2 } Messages Switched: ON Current Msg: 1 1. You feel your life force gradually slip from you. How sad, somebody has placed a curse on the Player. If no solution is found, the Player's health will slip below zero, meaning the Player dies. 3. Change User-Attribute Syntax: Change <object>'s <Type 1 Attribute> <value> <pronoun> <Type 2 Attribute> <Type 3 Attribute> 84 Figment User's Guide The Story Editor Used to specify a value to add to the object's specified attribute value. If the object does not have the attribute, the attribute is added to the object and set to the value. The value can be positive or negative. Attribute values are signed 8-bit integers meaning they can vary from -128 to +127. This function does not permit overflow. If you add 5 to 124 for example, the result will be 127. The different attribute types are accessed by hitting the Home key. 4. Change_score Syntax: Change_score <value> Changes the player's score by the amount specified. Values can be positive or negative. 5. Close Syntax: Close <object> Set the object's "open" attribute flag to read "CLOSED". The open, close, lock and unlock functions are more powerful in the rules than they are for the player during play. The player can only perform these operations on objects whose sub-type attribute is set to "Container", and only when the object's permission flag lets them. The story designer, however, can perform these operations on any object. This, in effect, reserves this flag partially for private use. 6. Copy_Msg_To Syntax: Copy msg to <character>'s view of <object>'s Long Desc. <pronoun> Brief Desc. Exam. Msg. This function copies the rule's current message to the specified viewpoint of an object. The old object text is lost. The message is also printed to the Command Window unless the rule specifies that printing is switched off. If the message you are copying is of zero length, it will effectively erase the destination string. 85 The Story Editor Figment User's Guide When editing this function, set the destination object's name first. The system will then scroll the legal viewpoints for that object. Since many objects have only the default, Player, viewpoint, the viewpoint scrolling will often be frozen at "Player's view". Copy_msg_to is commonly used in conjunction with repetitive rules (While and For) and the Inc_msg function to create message progressions: For 1 to 4 by 1 { <some conditions> } Then { copy msg to Player's view of <object_name>'s Long Desc. inc_msg } Message 4 Total Switched: OFF Current Msg: 1 <4 messages specified> In the example above, the rule type "While" could be used instead of the "For" type, because Inc_msg stops at the last message so the message progression stops harmlessly. Of course a "While" could not be substituted for the "For" if the statement were changed to "For 2 to 8 by 2 {...", which slows the progression down to every other count. 7. Go_to_Map_Block Syntax: go to Map Block <Map Block> This executional function will change scenes from within a rule base. When a rule fires and this function is encountered, the scene will change to the new scene as specified from the Story Map block number. Assume the pre-command rule base for a given scene includes the following rule: While { Player does eat Magic Cookie } Then { Go_to_map_block 3 Thru Looking Glass } ... This function behaves differently than other executional functions. Normally an executional function just executes immediately. However, changing scenes also means the rule base will change so a jump to a new scene in the middle of processing the rule base would also jump you to the middle of another rule base. Not good. Moreover, we want all the other rules to have 86 Figment User's Guide The Story Editor their chance to vote on the action as they do with all commands. Therefore, this function is designed to wait until the pre- and post-command rule bases are completed before jumping to the specified scene. If you use this function in a pre-command rule as in the example above, you can control it with the "Enable" switch. If you disable the function, the post command processing is not performed and the jump to the new scene is also not performed. Other pre-command rules can also be testing for the "eat" command, and they in turn might disable the "eat" command and thereby inhibit the jump. If there are multiple rules checking for a command, you will probably want this rule to be a "While" rule. Otherwise, it will expire, but Figment will not jump to this scene, when other rules block the command. When the player's actions eventually satisfy the various rules involved, the "while" rule can still fire and trigger the jump to the new scene. When used in a post-command rule, Figment will allow the post- command rule base to complete before changing scenes. Then, it changes scene and cycles through the post-command rule base for the new scene. This method preserves the appearance of a "go" command. Notice that you are specifying map blocks, not scene object names. If you are using a complex map (see the User's Guide for a discussion of complex maps), you will get the correct map block that you want. 8. Inc_moves Syntax: Inc_moves Used to increment the move count when your rule disables the player's command and you do not want to give the player a free move. It increments one move at a time, but you can use it several times in the same executional clause. 9. Inc_msg Syntax: Inc_msg Increment the rule's message pointer one message after the message has been displayed on the command line or copied to an object (see also Copy_Msg_to). Rules can have a total of up to 87 The Story Editor Figment User's Guide 16 messages, but usually less. Inc_msg will never exceed the existing total. If Inc_msg were to execute five times while the message total was set to 2, the second message would appear four times. For 1 to 5 Step 1 { <scene> is_linked_to Stage Coach } Then inc_msg } Message 5 Total Switched: ON Current Msg: 1 1. You see a cloud of dust on the horizon. 2. Hmm. It's the Wells Fargo Express. 3. You pull your bandanna over your face and check your pistol. 4. Thundering hooves drown out your pounding heartbeat. 5. You race from hiding and rob the stage. 10. Kill Syntax: Kill <character> Usually used by the Story Designer to terminate the player and hence the story when the player attempts a conspicuously bad action. It can also be used to defeat the conflict "escape clause" (see also is_dead). 11. Link_to Syntax: Link <object> to <object> by <link_type> [<value>] <pronoun> <pronoun> Adds a reference to the second object in the first object's link list. The Link function creates a link of the specified type and sets the value to the specified value. Example: ...} Then { Link Romeo to Juliet by Romance 12 }... You cannot make duplicate links with this function. If the link of the specified type already exists, the expression value is merely added to the existing link value. 88 Figment User's Guide The Story Editor 12. Lock Syntax: Lock <object> Set the object's lock attribute flag to "ON". 13. Msg_to_name Syntax: Msg_to_name <object> Copies the rule's current message to the object's name thereby renaming the object. This is fully legitimate and often done. Since Figment is designed to reference the current object name at all times, your rules using the old name are automatically switched to the new name so they function as intended. 14. On_skill Syntax: On_skill The on_skill function sets the rule's message pointer according to the Player's current skill level. There are 5 skill levels and 16 possible messages. Thus the first message is used for the first (novice) skill level, and the second message for the second level, etc. You are not required to specify a message for each level. The message pointer then stops at the highest message specified. For example the following rule generates one message for novices and a more informative message for more experienced players: If { Passage Door is_locked } Then { on_skill } Message 2 Total Switched: ON Current Msg: 1 1. The sign reads: "Forbidden Zone". 2. The sign reads: "Forbidden Zone", but you don't believe everything you read do you? This function is special in that it must appear first on the list of executional functions for the rule, otherwise, it will be ignored. 89 The Story Editor Figment User's Guide 15. Open Syntax: Open <object> Set the object's "Open" attribute to read "OPEN". This function does not concern itself with the status of the object's lock flag. 16. Remove_User_Type Syntax: Remove user type <label> from <object> <pronoun> If the object in question has the specified user-defined type, then this function will remove it. See also "Add User Type". 17. Take_from Syntax: Take <object> from <object> Removes a link entry in the second object's link list that refers to the first object. If the object is not linked to some other object, it is out of play until another rule links it to something. If { <test conditions here> } Then { take Royal Jewels from Player add Royal Jewels to <scene_name> } ... The above example is equivalent to the command "drop" except the player does not give the command. Since no message is given, the player might not even be aware that it happened, although the object's description will now appear in the scene description. 18. Toggle_lock Syntax: Toggle_lock <object> Changes the object's lock attribute flag from ON to OFF or from OFF to ON. See also "lock" and "unlock". 19. Toggle_open 90 Figment User's Guide The Story Editor Syntax: Toggle_open <object> Changes the object's "open" attribute flag to OPEN from CLOSED or from CLOSED to OPEN. See also the executional functions close and open. 20. Unlock Syntax: Unlock <object> Changes the object's lock attribute flag to OFF. See also the executional functions lock and toggle_lock. 91 The Story Editor Figment User's Guide P. Player Maps Figment uses the Story Map to track scenes and the directions from those scenes to other scenes. The Player is assigned a similar map to track map knowledge acquired as a result of play. The Player Map tracks the scenes that the player has visited and the directions used from those scenes. Initially, the player has a very limited knowledge of the Story Map. Only the starting scene is known at the start of play(, but the author can specify more). When the player moves to a different scene, the player's knowledge of the new scene is added to the Player Map. The player only acquires the direction knowledge that he or she has actually used. That is to say, just because you have visited a scene, does not mean that you know all the possible exits from that scene. The "go" command during playback can refer to places (scenes) by name and Figment will compute the path to the scene from the Player Map. Similarly the "find" command computes a path to a scene that has the object the Player wants to find. Often, you want to give the Player foreknowledge of places and things. For example a story about a haunted house would probably speak of the public rooms: living room, dining room, front hall, et cetera so you want people to refer to them naturally by name as in "go to the Living Room" or "find the coffee table". On the other hand, you do not have to tell them about the secret passageway in the library. The Story Designer can edit the Player Map to provide any amount of environmental knowledge as required. Editing the Player Map is similar to editing the Story Map, but the Player Map can never be more than the Story Map. You are not really constructing a map when you are editing the Player Map. You are specifying values as "on" or "off" meaning the player knows or does not know this scene or direction. The Player Map screen editor is accessed from the Top Level Editor. It is the screen following the Story Map. You move the cursor in the same manner as with the Story Map, but the values that scroll are restricted to only those contained in the Story Map. Thus when you set a value in the Player Map you are saying that the player knows this scene or a direction from this scene in the Story Map. You cannot add or delete blocks from the Player Map. You are restricted to the same blocks as defined by the Story Map. You turn them off or on by moving the cursor to the appropriate location and scrolling up or down with the up-arrow or down- 92 Figment User's Guide The Story Editor arrow keys. You cannot edit the directions from a scene until you specify the scene in the map block title. (The Player cannot know the exits from a scene until the scene is known). If you turn "off" the scene in the block title, any directions you have specified are also turned off. If you want the Player Map to be equivalent to the Story Map, you can dump the Story Map to disk with F3, change the screen to the Player Map and read the map data into the Player Map with F2. This is a handy technique since it is often easier to say what you don't want than it is to say what you do want. It is a good idea to compare the Story Map with the Player Map you are making. This is easy to do. Go to the Top-Level Editor and switch between the two screens while studying one block at a time. You will notice entire blocks or exits from blocks that you will want to specify. Q. Synonym Editing Figment allows you to specify synonyms for both functions and objects. A synonym simply allows you to substitute any phrase consisting of any number of words for a Figment command or an object name in the story. It allows you for example to say: >cut the rope or >pick up the rock instead of: >unlock the rope or >take the rock In the examples above, you would still write rules that test for the "unlock" and "take" functions. Rules will never refer to synonyms. "Cut" is not actually a command. Synonyms take a lot of the frustration out of stories, and their use is encouraged. Synonym editing is simple and straightforward. By now, the method should be easy. Page-Down from the Top Level Editor puts your cursor at the top row of synonyms. Page-Up and Down again moves you up and down the rows of synonyms. Up-arrow on the function scrolls the function names. Left and Right-Arrow moves between the function 93 The Story Editor Figment User's Guide and the phrase. The phrase is a text string edited in the normal manner by re-typing or editing with F6. New synonyms are created by hitting the "+" key and they are deleted with the "Delete" key. Synonyms are written and read to the story file so they form a part of your story. They can be dumped separately so that you can move them into new stories. You will want to do this. If you get used to saying "look" for "examine" you will quickly notice its absence in your new story. Object Synonyms are accessed by advancing the cursor further right. They are edited in the same manner as function synonyms. You can have up to 64 synonyms, but the screen can only display 20 at a time so you when your cursor reaches the bottom line, the screen starts rolling the lines upward. Thus you see a window of synonyms. Escape is a rapid exit from Synonym Editing. R. Parameter Editing Screen This screen editor includes three separate editors: the Parameter Editor, the Status Editor, and the Object Type Editor. From the Top Level Editor, Page-Down. The cursor lands on the title "Parameters". You can advance the cursor to the titles "Status Editor" and "User Type Editor" to access those editors. There is also an indicator panel to tell you how full your story is to aid your planning. This indicates the number of objects used and the percentage of object capacity consumed. The same is true for expressions and rules. This capacity refers to vacant pointer capacity. Text strings, objects, rules and expressions are allocated memory dynamically when you create them so they compete for memory on a first-come-first-served basis. Figment then points to that memory space. Therefore even though there are vacant pointers, there is no real guarantee there will be memory available when you want to create these items. If you write long text strings, there will be less memory available so you must settle for fewer objects, rules, and expressions (and hence the fewer text strings these engender). When you run out of memory, all you can do is start a new story as "Part II - The Saga Continues". This is legitimate since you must archive and perhaps ship your work, and in the DOS world, 94 Figment User's Guide The Story Editor the lowest common denominator is the 360 KB floppy. This means your work must break into pieces that fit the range of 250-350 KB which is what you get when you run out of memory in Figment (with 640 KB installed). 1. Parameter Editor Parameter editing allows you to change some fundamental story parameters. By now you should understand the editing process enough that we can dispense with discussions of page-down and arrow keys and simply focus on the parameters themselves. a. The Title The title is a text string that you provide. You may use this to include your copyright statement if you like. Be very careful about changing anyone else's copyright statement. It is illegal to distribute someone else's copyrighted story to people even if you make no money from the transaction. If you heavily modify someone else's story and attempt to copyright it as your own, it forms what is known as a derivative work and distributing it can still be illegal regardless of whether it was for profit. Consult your lawyer. The title with its copyright statement is written to the save file and fulfills the requirement of the copyright laws for embedding your copyright statement in the data files. It is also displayed each time the story is retrieved, also in compliance with the requirements of copyright law. Most texts on copyrights say it is good practice to make a copyright statement early in the development process. You never know if you might want to publish it. The title message is allocated its own screen at the start of the story. If you define a title message, Figment will pause after printing it and print the message: "Strike any key to continue." The intention is that you will define a title with perhaps a copyright statement, an abstract or introduction, any licensing or copyright statement, etc. The user's name is also requested in the title message processing whenever you include the word "@Get_User" in the title. You can do this at the start of the title, and echo it back later in the message with "@Full_name". The name is parsed into the @User[] names, and the Player name is set to @User[0], the user's first name. Usually during development, you do not want to be bothered with 95 The Story Editor Figment User's Guide user name processing so you omit the keyword "@Get_User" from your title. Later when you want to distribute your story, you replace the keyword. b. Moves and Score The move count and the score can be adjusted here. The Shift-F3 function automatically zeroes them before saving the data. You can adjust the move count and score in order to modify the skill level (displayed here for convenience) for debugging skill- dependent sequences. The Move counter must be greater than zero in order for the skill level to change, otherwise a divide-by- zero error would occur. c. Recuperation Parameters "Recup-int" means "recuperation interval". When the Player's health is low, Figment restores the Player's health slowly over time to represent a healing process. Increasing this interval slows the recuperation process while decreasing it speeds it up. d. Food parameters "Food-cnt" tracks the current food point status. This value increases as the player consumes food and decreases one point at a time in an interval specified by "Food-dec-int". Setting a high food count and a large interval will effectively eliminate food concerns from your story if you would rather not bother with it. Going the other way will have your player consuming everything in sight in a desperate attempt to stay alive. Figment begins warning you when the food count is getting low. "Food-msg-int" specifies the interval between these messages. The appropriate size would be: initial-food-count * food-dec-int / 5 = food-msg-int You can always specify other values of course which can make Figment more or less of a food nag. 2. Status Editing The status banner displayed at the top of the screen during playback can be modified to display the parameters and attributes you want to use. 96 Figment User's Guide The Story Editor The status banner is composed of active elements that report the various parameters as formatted text. The various text pieces are strung together as a single line of text. Hit the "+" key to add a new element. Hit the "Delete" key to remove an element. Scroll the parameters using the up- and down-arrow keys. Hit the Home key to access a different data type. The data types are arranged as follows: Story Parameters: Score, Moves, Current Scene Name Actor's System Attributes: Skill, Strength, Health, etc. Actor's Category I User Defined Attributes Actor's Category II User Defined Attributes Actor's Category III User Defined Attributes Repeated strikes of the Home key will cycle the data types from Story Parameters through the System Attributes and on through the various User-Defined Attributes. 3. User Type Label Editing User type labels for objects are text strings that you create to describe things. They might be character types: "Cleric", "Warrior", "Thief", or they might be object types: "Car", "Boat", "Plane" or anything else you can think of. You might also categorize scenes: "Chase Scene", "Death Scene", "Romantic Interlude", etc. To create the labels, go to the Parameter Editing Screen, move the cursor to the heading "User Type Editor", and hit Page Down. Hit "+" or Page-Down to create a new entry. Type in your label name and close by hitting the "Return" key. As you add labels, the column of labels grows and spills over to a new column. Eventually all columns are full and they begin scrolling like a moving belt until finally you hit the maximum system capacity. You can add and delete labels with "+" and "Delete" keys. You can navigate the columns with the Up-, Down-, Left-, and Right- Arrow keys. The Page-up and Page-Down keys will also navigate up and down the columns, but Page Down adds new labels when you reach the end of the list and Page Up exits when you reach the top. The "Escape" key is a rapid exit from this editor. Labels can be as many characters long as you like, but we often can only print the first 10-16 characters so brevity helps. Don't make duplicate labels. 97 The Story Editor Figment User's Guide When you delete a label, Figment checks for references to that label in other data structures. Object type labels are used in objects and rule expressions ("is_user_typ" and "assign"). If some data structure uses this label, Figment reports it and stops. You must remove this reference by going to that data structure and deleting the reference before you can delete the label. There are probably more references like this one so you will want to check for them before returning to delete the label. When there are no references to a label, it is easy to delete it. Therefore, you may want to think through your labels before committing to many references to them. It is much easier to rename a label. Just type a new name for the label. All references to the label will reflect the new name. Figment really does not know what your labels mean, it only knows that deleting them can destroy a lot of other work so it checks before deleting. This process is deliberately similar to that for the Link Types and the User Defined Attributes so once you get the knack, the others follow neatly. S. Link and Attribute Type Definitions A separate editing screen is used to specify the link types and attribute types. The method of editing is sufficiently similar that we can discuss them together. The process is very similar to that for User-defined object types. As before, Link and attribute types are merely text labels that you create to identify a link or attribute you want to use. From the Top Level Editor, scroll the editing screens to display the Link and Attribute screen and hit Page Down. Advance the cursor to either Link Editing or Attribute Editing. Hit Page Down again. Edit the text in the usual manner. The labels you make can be as long as you like, but screen space limitations mean we can often only display 10-16 characters depending on where they are used. Abbreviations are fully legitimate. Use them as needed. Do not duplicate link labels. User Attributes can duplicate if the duplicate labels are in separate categories. For example, "strength" might be a physical, psychological or spiritual attribute for a character. If you felt that way, then you would list strength separately in each category. You can delete link types and user attributes. As with object 98 Figment User's Guide The Story Editor types, Figment reports the first conflict it finds and stops. Delete the reference, and you can come back and delete the label. Link labels are used in objects and rule expressions ("is_linked" and "link"). Attribute labels are used in objects, rule expressions, and profiles. You cannot delete link type "Generic". The editing keys work in the by-now-familiar manner. "+", Delete, Page-Up, Page-down keys perform as they always do. The ESC key is a rapid exit to the next highest level. T. Profiles Profiles are a weighted decision matrix applied to an object's user attributes. They allow you to list attributes and apply weight factors to arrive at scores. The resulting scores can return TRUE/FALSE values if they are above or below the cutoff criteria. For example, assume you want to determine if Romeo and Juliet are lovers. You might write the following rule: If { Romeo does fit profile of Juliet's Lover Juliet does fit profile of Romeo's Lover <other conditional expressions> } Then { Link Romeo to Juliet by Romance Value 20 Link Juliet to Romeo by Romance Value 20 } ...<sound of violins and waves crashing on beach> Certainly people have complex criteria for choosing partners, but rules can't equivocate. They need a yes/no answer. Does Romeo qualify or not? Profiles let you score candidates and bias the scores giving more or less emphasis to attributes you think are more or less important to this decision. A high score means Romeo makes the grade. We will begin by assuming that Romeo is the strange bird referred to earlier in our discussion of attributes: 99 The Story Editor Figment User's Guide Type 1 Type 2 Type 3 Strength 50 Courage 10 Devotion 10 Beauty 20 Bravery 2 Purity -40 Warts 10 Paranoia 33 Je ne sais quoi 100 Bad Smell 15 DrinksLikeFish 99 Chemistry 12 Dresses Funny 10 Morals 0 Kind to Animals 23 Ok, he's no prize, but focusing on some of his nobler qualities we might extract a subset list and apply weight factors to signify importance like this: Profile of Juliet's Lover Type 1 Wt. Type 2 Wt. Type 3 Wt. Strength 50 Courage 10 Devotion 10 Beauty 20 Bravery 2 Je ne sais quoi 10 Warts 10 Chemistry 120 Kind to Animals 23 In a Profile, weights are given simply as a value from -128 to +127. Higher values mean they are more important. The default value is one, meaning no weighting is given. So how does Romeo stack up? Filling in Romeo's attribute values on this score sheet gives: Profile 1 of 2 Name: Juliet's Lover Candidate: Romeo Type 1 Wt. V. Sc. Type 2 Wt. V. Sc. Type 3 Wt. V. Sc. Strength 1 50 50 Courage 1 10 10 Devotion 10 10 100 Beauty 2 -20 -40 Bravery 1 2 2 Je ne sais 1 100 100 Warts -10 10 -100 Chemistry 3 12 36 Kind to An. 1 23 23 ----- ------ ----- -90 120 259 Class Wgt: x 10 x 30 x 5 ----- ------ ------ Sub Total: -900 360 1295 ====== Total Score: 755 Cutoff: 500 In this example, Romeo makes the grade. His total score beats the specified cutoff value, thanks to a strong showing in category three which overcomes Juliet's strong dislike for warts. The Class Weight applies the weighting principle again, but this time to the categories as a whole. For example a relationship might be platonic or physical, in which case you would stress those groups of attributes by increasing the class weights. 100 Figment User's Guide The Story Editor The candidate is an object you intend to use with this profile. You can scroll through different candidates to see how they would match up against your criteria. As you change the candidates, Figment displays their values for the specified attributes and re-scores the profile. The candidate is merely a de-bugging tool. It has no effect on your story. You can jump into the editor anytime during playback and check different candidates and profiles. This example also illustrates one way to handle negative attributes. Juliet has placed a strong negative bias on the "Warts" attribute. Fortunately she compensated in the intangible qualities in category III or poor Romeo would still be searching the personal ads. A profile is, by design, an average of the many components. Sometimes you want to be more discriminating. Multiple profiles can help: If { Player does fit profile of President Player does not fit profile of Loose Cannon on the Deck }... You can put the good qualities in the profile called "President" and put the bad qualities in the profile "Loose Cannon on the Deck". This way you can be sure that the bad qualities will not be masked by overwhelming good qualities. Profiles can be deleted, but if Figment finds a conflicting reference, it will report it and stop. You must remove the reference before you can delete the profile. Profiles are referred to in rule expressions ("does_fit"). U. Standard Messages and Text Variables Standard messages can be used as "text variables" to create specially-adaptable messages. Text is used in several places: object descriptions object examination messages command responses (from rules firing) Wherever text is written, the user can include the special text symbol: "@Msg: nnn", where nnn means some number, three decimal digits or less. Figment will remove this symbol during 101 The Story Editor Figment User's Guide processing and insert the message as specified by the number. (see @-Words) A separate editing screen is provided where the developer can write these standard messages. Their only identifier is their number so they are referred to as Standard Message 1, Standard Message 2, etc. to differentiate them from rule messages. By themselves, Standard Messages can simplify development and maintenance. Where a line of text is used frequently, the developer can write it once and use it repeatedly. Maintenance is thereby simplified too, because only one instance must be corrected. Further, you can create text composed only of standard messages. You can write rules that copy their messages to the standard messages. The result is that the standard messages function like text variables to form a larger body of text that changes as different rules fire. When you are using Standard Messages as Text Variables, the message can look odd, because it is often just a scrap of text. A standard message might read: 12. and it has the old text I don't want anymore. Then the object's examination message can include a reference to Message 12 among the text that it reports: "This is the object's examination message, @Msg: 12" making the examination message read: "This is the object's examination message, and it has the old text I don't want anymore." 102 Figment User's Guide The Story Editor A rule might then say: If { <something> } Then { copy msg to Standard Message 12 } Messages 1 Total Switched: ON Current Msg: 1 1. and it has the new text I want to see. When the rule fires, the examination string now reads: This is the object's examination message, and it has the new text I want to see. Of course text can be composed only of Standard Messages: "@Msg: 5 @Msg: 2 @Msg: 9" or if you want paragraph breaks in the report: "@Msg: 5 @Msg: 2 @Msg: 9" The result is a unique string composed of standard messages which can be changed as rules fire and copy their messages to the Standard Messages. It is probably difficult to make a reasonable body of text if you are trying to manipulate a composition made from more than a few messages. Complexity rises rapidly here. Standard Messages can be used in lieu of a unique string. The advantage to the developer is that rules and objects can share the same messages. This can make development simpler. Otherwise the message would have to be duplicated and when making revisions the developer must make duplicate revisions too. Standard Messages are most useful for examination messages and command responses coming from rules that fire. Descriptions are already complex enough since they are composed of several individual elements gathered from the objects in the scene. 1. Editing Standard Messages Editing the messages is easy. From the Top Level Editor set the Standard Message Editor screen with the up/down arrow keys. Hit Page Down. This adds the first message for editing if none already exist. The cursor lands on the first message. The 103 The Story Editor Figment User's Guide up/down arrow keys moves the cursor to the next message for editing. The Page Up/Down keys move through long lists of messages one screen-full at a time. Escape exits the editor. The '+' key adds new messages. The text itself is edited in the normal manner once you have put the cursor on the message you want to change. F6 invokes the full-screen editor if you want to view very long messages. Deleting standard messages can cause headaches. If you delete Message #2, for example, Message #3 becomes #2. If your text refers to Message #2, it will get a different message than was originally intended. This reference has to be edited manually by changing the text. Not fun, especially if there are 30 messages after #2. Consider just blanking the message instead. You can use it later if you need another standard message. V. Full-Screen Text Editor The full-screen editor implements a limited sub-set of text processing commands available on full-function word processors. It is designed so that it can be invoked seamlessly from the typing buffer since most story messages start small and grow suddenly when inspiration strikes. To invoke the text editor, simply hit F6 at any time while typing text anywhere in the Story Editor. The screen erases and the text you began to type and the text it was replacing are put into the editing buffer and displayed on the editing screen. The cursor keys now behave like word processing keys: Left- or Right-Arrow moves the cursor one character. Up- or Down-Arrow moves the cursor one row. Home moves cursor to start of row. End moves cursor to end of row. Page-Up moves cursor to start of buffer. Page-Down moves cursor to end of buffer. Ctrl-Left- or Ctrl-Right-Arrow moves cursor one word. Ctrl-end deletes text from current cursor position to the end of the current row. Delete deletes one character in front of cursor. Backspace deletes one character behind cursor. Escape exits the editor. 104 Figment User's Guide The Story Editor CTRL-X exits editor, but discards the changes returning the original string unchanged. Use this when you goof. Just type text as you would in any word processor. When you are through, simply hit the key labeled Escape. The screen then erases and you find yourself back in the Story Editor with your cursor pointing to your new text string. The editing buffer is limited to 25 lines of 80 characters. (When we say it's a full-screen editor, we mean it - ONE full screen.) See also the discussion on hard and soft returns in section I.A.2. titled "Editing Text" earlier in this document. Tabs are not implemented in the editor since their results would be unpredictable during playback as messages are combined in different ways. W. File Management Playback quickly alters the data you so carefully edited so good file management skills are important to protect your work. Figment can produce a great many file types that may seem confusing at first. This section discusses these various files so you can manage them properly. 1. File Naming Conventions When you start a story, default file names are constructed from the story name and some standard file extensions. Other utilities like logging and scripting also produce files with special name extensions. You can recognize the type of file by its extension. These extensions are: .sdf - story data file .sav - saved data file .bak - last saved file .lst - listing or script output .log - log file Of these, the files you really want to archive are the Story Data File and the text form of your log file if you have one. The rest can be periodically purged from your disk. The DOS batch file, "purge.bat" is provided for that purpose. Edit this batch file to suit your needs, but rename it so it will not be clobbered by the old purge batch file when you upgrade. 105 The Story Editor Figment User's Guide You should recognize the story file by now since it is the file that you read in at the start of the session. The save file is the file you write with the "save" command in the Presentation Environment or the Shift-F3 key in the editor. Figment cannot write a story data file (".sdf"). It can only write a save file (".sav"). In this way, the story data file is protected and never over-written. It preserves the data in the form you want it for startup. To make a story data file, simply rename a save file using the DOS command, "rename": rename demo.sav demo.sdf Another way is to copy the data: copy demo.sav demo.sdf You might do this at the end of an editing session so that the story data file is ready for the start of the next session. The save file represents work in progress. It is good practice to keep it separate from the story data file until you have had a chance to test it out and build confidence that it is doing what you want. When you are satisfied with it, you can rename it to a story data file. Some people like to copy it to a working name so they can start figment with that name, otherwise you must use "restore" after starting to get your working version loaded. copy demo.sav temp.sdf figment temp Later, you can rename or copy the working copy back to the intended name: rename temp.sav demo.sdf The best way to get started is to copy our demo file so you can begin creating your own files for practice. copy demo.sdf <new_name>.sdf Then start Figment with that name: figment <new_name> You can start a completely new story by making up a new name that does not exist on your disk. Use that name to start Figment: figment zilch 106 Figment User's Guide The Story Editor Figment finds no file named "zilch.sdf" so it starts without it. You arrive in Figment staring at a very dull story. You then enter the editor and begin creating your data. When you save your data, you have a new file called "zilch.sav" 2. Read-all, Write-all Shift-F2 and Shift-F3 are the primary read-write tools for developers. These are similar to "save" and "restore" in the playback environment, but there is one important difference. Shift-F3 is designed to prepare the save file for use as a story data file (.sdf file). This means it will set important data to the values they should have at the start of the story. For example, the move count and the score should be set to zero. The scene should be set to the first scene in the map, et cetera. The process sounds good on paper, but recognize the limitations. Figment cannot tell what the Player's health should be for example or any of many attributes and associations. Figment does warn you before editing if you have been playing your story so you should have retrieved your file from disk before editing. The Shift-F3 function really expects that you will be developing with a log file to play the story through a standard set of commands as you work to debug your story. Without this log file, the Shift-F3 function's automatic reset will certainly aggravate you. If you did not want the automatic reset, you could hit F1 to return to the playback environment and then say "save". This would save the data without the automatic reset. Except in rare instances, the "save" command is not recommended for developers. Use Shift-F2 instead. The "restore" command and the Shift-F2 function are the same. 3. Data Backups and Version Numbering After you quit Figment, you may want to make backup copies of the files you made on a separate diskette. Use the DOS COPY or XCOPY command to do this. At the least, you will want the ".sdf" file, but you may want any others you have been making, for example logs. The following command will copy all the files for a story from the current directory to a diskette in drive B. copy <story name>.* b:\*.* 107 The Story Editor Figment User's Guide You can, if you like, rename the files at this time and thereby create version numbers: copy story.* b:\story2.* The advantage, of course, is that you can go back and retrieve old versions should you discover some disastrous consequence of your editing. As mentioned previously, the listing file produced for the rules is expendable. You can see that if you do not delete it before copying the set, you will be proliferating obsolete listing files. We recommend that you print any listings that you want, then delete "*.LST" before copying the data set. The DOS batch file, "PURGE.BAT", will delete the data set files, the backup file and the listing file for a story. It will not delete story data files, log files, nor save files. It is a useful tool for cleaning up a disk or directory that is cluttered with obsolete files. To use it, simply type "purge <story_name>" (where <story_name> means you type the name of the story) from the DOS command line prompt. 4. The Data Set Files The Data Set read/write functions (F2/F3) have largely been superseded by the restore/save functions (Shift-F2/Shift-F3) and so have most of their applications. The Data Set files let you dump portions of your story so you can read them into a different story. They are not recommended for beginners or the faint of heart since there are many limitations and some pitfalls. The Data Set files are a low-cost feature. Their development cost is nil since the save/restore functions merely concatenate the individual data set read/write operations with a small preamble. A good application example for the Data Set files is the Link and User Attribute labels. These are often the same from story to story so dump them to disk and read them into each new story. Maybe you have a standard set of synonyms or profiles that can use the same treatment. Also Player Maps can be made easily by dumping the Story Map and reading it back into the Player Map screen. You can also move objects and rules between stories, but there is a serious restriction on moving objects; and rules, by their nature, are not often portable. Maybe the global rules will apply in a different story, but local rules, by definition, are 108 Figment User's Guide The Story Editor intended to be specific to a scene. Maybe the best method for objects and rules is to print listings so you can copy a technique you developed before. Each screen in the editor has a Data Set file assigned to it. This is the default file for dumping that screen's data type. We recommend you use those names since they establish a naming convention for the files produced. You can change the name simply by moving the cursor over the name and editing the text in the usual manner. .stf - stuff data .scn - scene data .pre - pre-command rule data .pst - post-command rule data .smp - story map .syn - synonym data .prm - parameter data (includes status and object type labels) .lua - link and user attribute labels .prf - profiles .msg - standard messages You can only read or write a file from the Top Level Editor. F2 and F3 do not function in the lower level editors. Hit F3 to write the data out to the file named as indicated on the top of the screen. Note that the file name lights up in reverse-video until the write completes. If the file already exists, its contents are completely overwritten. If the file name indicated is not the file to which you want to write, advance the cursor with the Right-Arrow key to the name and type in a new name. Hit F3 again. Note that this does not change the story name nor the name of the ".sdf" file built from the story name. (The story name is only changed with the save, restore and restart commands in the story side of Figment.) A similar process applies to reading files except you hit F2. If Figment beeps when you hit F2 or F3, it means that it could not open the file in question. Maybe you have been juggling diskettes or typed the name wrong. Remember that you can jump out of Figment with F10, shuffle files around on your disks and return to Figment to write your data. Filenames are text strings which can include the path to reach the file which means that you can park files on other disks or in sub-directories on hard disks. We have said that you should always write your data out after making any changes, because you will go next to the Presentation 109 The Story Editor Figment User's Guide Environment and test your changes which will alter the data. Usually, this will be a save file made with the Shift-F3 key, but for testing small changes sometimes you can use a data set file and throw it away if you decide the test was not worth saving. 5. Experimental Variations The Data Set files can reduce the cost of experimentation. For example, assume you are working on version 3 of your story and you decide you do not like the way you have changed the pre- command rule base. You do not want to throw version 3 away, because developments in other areas have merit. You just want to put the old rules back. This procedure will extract the Pre-command rule base from version 2 and load it into version 3: Caution! Never attempt this procedure with object data files. It works with all other data file types though. 1. Save version 3 with Shift-F3 2. Return to playback mode. Restart or restore version 2. 3. Enter editor, display pre-command screen, dump the pre- command rule bases with F3. 4. Return to playback mode, restore version 3. 5. Enter editor, display pre-command screen, change read filename to "version2.pre", hit F2. This example works whenever the object set (meaning in this case the names of the stuff and scenes) was not changed between revisions. If the object names changed between version 2 and version 3, the rules will show "Not Found" when a change is encountered, meaning the object name used in the data file was not found in the current object list. Notice that you can carve up version 2 all you want before you write the rule base out to its data set file(s). As long as you do not save your changes with "save" or Shift-F2, there is no harm done. This means you can fix the object names in version 2 before you write out the rule base. Then, you will not get the "Not Found" references when the rule base reads into version 3. What happens if version 3 has deleted a map block? The rule base from version 2 will not match the rule base for version 3. Again, the solution is to delete the same map block in version 2 before writing the rule base out to its data set file. Then, it will be in the right order when it reads into version 3. 110 Figment User's Guide The Story Editor 6. Object References in Data Set Files As mentioned previously, Objects are the building blocks for stories. Many other data structures refer to them, and it is these references that cause problems when moving data via the Data Set files. Whenever a data structure cannot find the object being referred to during read-in, it substitutes a reference to a dummy object called "(Not Found)". Actually "(Not Found)" is a stuff object in its own right. It merely lacks the links, text and attributes your original object had. As you play your story with this object, you notice missing descriptions and rules that do not fire when they should. Jump into the editor and you find a rule referring to something not found. In fact, this is probably the first thing to look for if you have been juggling data with F2/F3. The "(Not Found)" reference will remain until you edit it out. It does not disappear on file write/read operations. You can ignore them and play your story and correct them as you find them if you do not want to go on a witch hunt. Usually, you do not make wholesale revisions to your object names so one or two quick edits puts you back in shape. If you are looking at a screen where you can clearly read "(Not Found)" just add the object you need and edit the reference to read as it should. Problem solved. If this is a rule, the problem probably occurs in several rules so check other rules as required. Note that a similar problem occurs when reading Scene data files since their link lists refer to Stuff objects. Also with maps since they refer to Scenes. Rules refer to both stuff and scenes. X. Deleting Objects As mentioned earlier, deleting objects is easy: advance the cursor over the object name and hit the "Delete" key. The problem is the object references, and it is similar to handling the "(Not Found)" problem. Figment inserts a reference to a dummy object named "(Deleted)" wherever there is a reference to an object you are trying to delete. When all references have been replaced, it safely deletes the object. Figment cannot resolve what to do with these references so it does not try. It simply leaves this dummy in place for you to correct at your leisure. There are many places this object might be referenced: 111 The Story Editor Figment User's Guide Link lists in other objects Rules Story and Player Maps Deleting one object can make many references to the "(Deleted)" object. Deleting several objects at once simply makes more references and it can make it hard for you to figure out the right correction. Maybe you want to delete one object at a time. Note when deleting scenes that this does not remove rule bases. The map block that referred to this scene is simply titled "(Deleted)". Only when you delete this map block in the map editor will the rule base for that map block be lost. You may play your story with the map still referring to deleted scenes. When you arrive in a deleted scene, Figment politely reports, "This scene has been deleted." This should be your cue to fix your map. You can leave these references to "(Deleted)" in place, play your story and fix them when found. The sky has not fallen and panic is not required. You can even write and read the story to/from disk. The reference to "(Deleted)" stays with you until you are ready to fix the reference. It is simply a civilized reminder that you have some editing to do. As with all edits you will want to write the repaired data to disk when done. Recognize that if you are deleting an object just to replace it with a different object, then you should not delete the object at all. You should rename it. Y. Debugging Tips By now, it should be clear that the data in the editor reflects the current state of the story when you entered the editor. This means that the editor functions well as a debugger because it can display any data at will. Coupled with a log file and its pause, interrupt and single-stepping features, this is a powerful debugging technique. This section gives you advice for what to look for in the editor when you have a problem with your story. Once you have identified the problem, read in the data from disk to reset the data to the starting condition, fix the problem, then file the data back out and go back to the Presentation Environment to try your fix. If you are not getting the messages in the description you expected, check the scene object and the objects in the scene. If the messages are there, but not displaying, check the 112 Figment User's Guide The Story Editor attributes. If the attributes are wrong, the object might be ignored. If the attributes are right, look at the scene object to see if the offending object is linked in to the scene. Most likely this problem occurs with new objects when you forget to set the attributes or link it into the scene. If you are not getting messages you expect from rules, you can have several problems: Check to see if the message has switched off. Check the rule type. Is it an "If" rule that has switched off when it should have been a "While" rule that would stay on? Do the conditions hold true? If the rule conditions require links between objects, do those links exist? Is the message pointer displaying the wrong message currently in the editor? Did you leave the message print switch set wrong? Did you omit an "inc_msg" step in the executionals? Check Pre-command rules to see if you forgot to set the enable/disable switch. Check the order of rules. Does a rule that should establish the conditions for this rule come after this rule? Change the order. If you have been deleting objects or juggling data files, look for a reference to "Deleted" or "Not Found". 113 Story Design Figment User's Guide Part III. Story Design So far we have discussed what Figment is, how it works, and its commands and procedures. This section discusses some of the finer points of story design that are not immediately obvious from the mechanical descriptions so far. A. Skill Level You need not worry about the skill level in the early stages of your story design. This is an embellishment that comes later in the evolution of your story. Once your story has developed a structure and you can point to key milestones in the play, then you can award points with "change_score" when the player completes certain tasks. Skill can be considered a measure of the player's efficiency. If the player achieves point awards (that you the story designer give the player) greater than or equal to the number of moves, then the highest skill level is achieved. There are five levels: Novice, Average, Pro, Expert, and Wizard. It seems nicer to award points steadily through the play in a scene rather than all at once at the end. This tends to signal to the player that he or she is making progress in the right direction. Several small milestones are better than one big milestone. You want to encourage your players, not send them on a forced march through a desert of no reward. A player's health grows slowly over time to a level limited by the player's skill. Since health points are the "fuel" for battle, player's with greater skill can start from a greater advantage. This is a minor point, however. Similarly, the maximum food-count that a player can achieve is also a function of skill. Thus excessive food is wasted on novices, while wizards get more mileage from their food. Maybe they are in better training. This too can be circumvented by setting high initial food values and slow decrement (metabolism?) rates in the parameter editor. A good rule of thumb might be to award a number of score points with "change_score" equal to the minimum number of moves required to complete a scene. (Actually, you will have to award a few extra points for round-off.) This strategy makes it theoretically possible to attain Wizard status although it will be practically impossible. The move count through a scene is also affected by the number of 114 Figment User's Guide Story Design conflicts that take place within a scene. Since these are variable, you will not be able to predict the move count exactly. You may have to average the move count over five or ten scenes and adjust your point awards accordingly. If you award more than the minimum number of points required for wizard status, the excess represents a bonus reserve for the player. Nice from a player standpoint. See also the discussion on strategic weapons later in this section since they are the only thing that absolutely requires skill. B. Examine Strings Examination strings are a useful way for providing necessary clues so that play can proceed. Stories that are forever stuck in the first scene are not fun. If your friends are completely stumped by your story, you can break the logjam with some clever clues. The "on_skill" function was specifically intended so you can pass clues at an appropriate level of difficulty based on the player's skill. You might choose to reveal more information to highly skilled players as a reward for earning their high status. On the other hand, you might take pity on beginners. In practice, you might do some of both at different times in the story. Examine strings are also used to write victory messages in conflicts. See also "Conflict Conclusions" later in this section. C. Health Points As mentioned your health suffers in conflicts. It also suffers from hunger. When the player's health is low, Figment begins a recuperation process by gradually incrementing the player's health until it reaches limits according to the player's skill. Depending on how you have composed your scene, you may have to speed this process up. You can manipulate this directly with executional functions in rules by concocting some literary device ("You discover a healing potion") and award extra health points with the "change_health" function. This can also back-fire ("Sorry, this must have been a bad batch."). Potions and food, when consumed, add their health attributes as 115 Story Design Figment User's Guide well. You can sprinkle them throughout your story, but you cannot dictate when the player will actually consume them. Players can be understandably gun-shy about them since they can also backfire on them with negative attributes. See the discussions on potions and food later in this section. You can also control the rate of recuperation for the story in the parameter editor. Fast-paced stories with many fight sequences may require faster recovery. Increasing the recuperation rate increases the probability that the player will escape defeat in conflicts. See also the escape clause description under "Conflicts" in this section. D. Strength A player's strength can grow steadily to the maximum (+127) value after sufficient conflicts if you do not create some pitfalls to reduce it. For a while, you can compensate for this with more potent bad guys, but eventually, you may have to prune the player's strength level. Poor health of course reduces the player's strength automatically. Similar thoughts apply to magic. There are no automatic reductions for magic so you must apply your own. E. Conflicts In order to start a conflict (Hex or Fight) the opponent must have some health points, otherwise you immediately defeat your opponent. If this happens, it probably means the story designer did not intend for you to engage this character in conflict. As a story designer, perhaps you do not want to signal your intentions so clearly. You may want to give all your characters some health points so they can put up some kind of fight. Note that you are not required to give your characters any strength or magic points. The player can engage these characters and quickly dispatch them. They must have neither strength nor magic for this to occur (Otherwise, the character might deflect you. Read on.). You do not grow by defeating wimpy characters without the necessary qualifications (magic or strength), but you get a point award as though this were a good thing to do. In fact, you might be eliminating someone who could help you solve a puzzle, in which case you won a small consolation, but lost in the end. An opponent who has only magic, but no strength will deflect you 116 Figment User's Guide Story Design if you attempt to fight the character. Similarly, you will also be deflected if you attempt to hex a character who has only strength and no magic. In this way, you are coerced into the correct form of conflict. Characters can have both strength and magic, in which case you can either fight or hex them, but not both since they (or sadly, you) will be eliminated by one conflict or the other. Although you are locked into a fight to its conclusion, the story still proceeds as you fight. That is to say that each wager counts as a move and the post-command rule base is still processed with each move. This means that other actions can still transpire while you are engaged in battle. Consider using "hit" and "charm" when characters gang up on you. At least then you might be able to retreat. Perhaps we should not tell you, but there is one loophole out of conflicts. The fight ends when you lose all your health, but Figment doles out health points when you are ill. If the killing blow drops you to zero only, and if it happens to be that move when Figment gives you a health point, then you are out of the fight but miraculously saved. We recommend you flee. (Yes, this was a bug, but we liked it so much we made it a feature.) 1. Conflict Conclusions You may have noticed there are no gruesome remains after dispatching your opponents in battle. (This is a family show.) Figment's little minions quickly spirit away the remains leaving any objects the character possessed behind as booty. This can be used as another way to introduce new objects into play since objects that characters have are not known to the player unless you happen to write messages mentioning them. Note that there is nothing to stop a player from taking these things directly from the character unless you write pre-command rules to prevent them. Of course it is extremely difficult to take what you do not know is there, but this knowledge quickly comes with repeat plays. (Skill from experience again.) When the conflict is over, Figment reports the examination message for the victor. Thus if you want a catchy message to appear at the end of the conflict, you write a Pre-Command rule that loads the examination messages for the character and the player. Since any existing examination messages are probably not appropriate for the moment of victory, you will have to write a rule just to blank them so you may as well write some appropriate message. 117 Story Design Figment User's Guide You can also use this rule to award points in advance in addition to the one that the player will get for winning. If the player loses the battle, the score is irrelevant anyway so there is no harm in awarding extra points in advance. 2. Negative Attributes in Conflicts The editor prohibits negative attributes for all objects except those of type "Thing", but the Player's attributes can go negative as a result of consuming food and potions. Since conflicts take the sum of the appropriate attributes in order to weight the outcome, a negative attribute can serve to handicap the Player. There are two possibilities. Consider them when debugging conflicts. One possibility is that the player's attributes themselves are less than one. In which case, Figment will not allow the player to enter the conflict in the first place. The second possibility is that the player may be carrying objects with negative attributes. Figment sums the attributes of the player's possessions to arrive at a value for weighting the results of the random number generator. Figment grants one small boon when dealing with negative attributes. If the sum of the attributes is negative, Figment adds the minimum to the Player's attribute to allow the conflict to proceed. In the extremely unlikely event that the player might win, the added attributes remain as a bonus even if the offending objects are later dropped. Whether or not the player succeeds as a result of this, depends entirely on the opposing character. If the opposing character is weak, then the player stands a fair chance of winning. This gives rise to an interesting situation: present two characters, one weak, one strong. If the player fights the weak character first, then drops the handicap, it is possible that the player will then have sufficient strength or magic to defeat the strong character, but the player must choose which to fight first. F. Links Links were originally very simple: A was linked to B, that was it. Now links include types and values which makes them significantly more complex to develop and track during play. Our advice to beginners is to ignore the link type and value until your work grows to a point that needs to distinguish the link type. A plain, vanilla, generic link is all you need for most 118 Figment User's Guide Story Design tasks. You can have links to as many as 32 objects, unless you have set the limit attribute to less. Restricting links in this way causes certain effects. For example, you may not want people to load a container too full. Characters with low link limits will refuse things that are given to them. Figment will not let you exceed the link limit set for an object. The most likely objects to exceed their limits are the player, any scene, and any container. The commands "put", "take", "drop", and "give" are designed to insulate objects against exceeding their limits, but there is no guarantee you will like the way it is done. For example, when you drop an object and exceed the scene's limit, you get the message "You drop the <object>...and it disappears!". This is really a statement of last resort, because players tend to function like hyperactive pack rats grabbing everything that isn't nailed down and dumping them in some convenient scene. Therefore setting a low link limit on a scene makes it a very inhospitable place for orphaned objects. The executional function, "link", cannot be so subtle. If this function encounters a limit during play, it prints a nasty error message to the command line. This message is really aimed at you, the developer, not the end user. If you have designed your story and tested it well, you should not see this message during normal play. Avoid duplicate links. They are fairly harmless, but you should avoid them anyway. The second link would be ignored until the first one was removed. The executional function, "link", will not make a duplicate link; it just changes the value when the intended link duplicates an existing link. There is nothing to say that an object cannot be linked into many different scenes. Often, this might be a standard feature so there will not be any confusion if the player should attempt to take the object, but it does not have to be a feature. Containers greatly expand your capacity. An object can be linked to 32 objects which in turn can be linked to 32 objects which in turn....well, there is almost no limit. Thus if the player has a container, the container can have its own container, etc. The player has to load these in sequence: >take ball >put ball in box <repeat up to 31 more objects> >take box 119 Story Design Figment User's Guide >put box in bag <repeat up to 31 more objects> >take bag but at least it is possible to nest objects several levels down. These nested objects would have to be unloaded in reverse order with the take-from command: >take box from bag >take ball from box See also the additional discussion on containers later in this section. G. Controlling the Random Number Generator Figment's random number generator gives you the ability to control it so that you can predict its behavior for debugging or training purposes. Computer random number generators require an initial starting number called a seed. Once this seed number is supplied, the routine can return an endless list of random numbers. The sequence is random, but the seed is not, hence the term "Pseudo- random". Indeed, for the same seed, you will get the same sequence. Figment supplies a new seed number each time you start so that the sequences will always be different. This is probably what you want during playback, but it is certainly not what you want when you are debugging stories, for example with log files. Therefore, Figment allows you to specify the seed when you start. Thus the command from DOS: figment <story_name> <seed_number> will start Figment with the specified seed number. The number is any integer between 0 and 32767. The number you choose is not important. So long as you use the same number every time, you will get consistent results when your log files encounter conflicts. This procedure is also useful for beginners and young players who want to simplify the conflicts. 120 Figment User's Guide Story Design H. Potions and the Drink Function The drink function tests to see if the object sub-type attribute is set to "Potion". If not, the command fails. When the player drinks a potion, the potion's strength, health, and magic attributes are added to those of the player. This is a good place to use negative attributes. Potions can be a mixture of some good qualities and some bad qualities. For example, a potion that increases strength might reduce health. If the player does not have the potion, but the scene does, then Figment performs an automatic "take" command. This take command is a fully legal take operation: any rules you have waiting for a take operation will fire, and anything that causes it to fail will cause the drink command to fail. The move count is incremented twice if taking is required. The post-command rules are also processed. A potion must be opened in order to be drunk. If the potion is not open, Figment will not open it automatically. The potion's limit attribute indicates how many times the potion can be drunk. I. Weighty Matters The weight attribute is another way to limit the player's possessions besides the limit attribute. It indicates how much the player can carry on the basis of weight, whereas the limit attribute indicates the quantity on the basis of count. If the player wants to take an object, that object's weight attribute cannot exceed the player's weight attribute (less the sum of the weights for any objects that the player is already carrying). You are not required to specify an object's weight; it can be weightless. This means you can ignore weight early in the story design and add it later to add another dimension to the story. Weight really only applies to objects of type "Thing" and varies from -127 to 127. Objects with negative weights are, in effect, lighter than air. Their negative value reduces the sum and allow the player to carry more weight: >take the helium balloon You feel lighter. 121 Story Design Figment User's Guide J. Size and Containers The size attribute is used with containers in much the same way that the weight attribute limits the player object. The size of an object to be added to a container cannot exceed the container's size as indicated by its size attribute (less the sum of the sizes of any objects already in the container). As with weight, you are not obliged to specify an objects's size. The player never is concerned with an object's size, only its weight. Containers can be somewhat magical in the sense that you can place many objects in the container and then specify an arbitrary weight for the container (even zero weight if you like) completely independent of the object weights. In addition, containers count as only one object so they greatly enlarge the player's carrying capacity. Size really only applies to objects of type "Thing" and varies from -127 to 127. Objects with negative size, when added to a container, have the ability to fit more objects in the container than would be possible without them. K. Waving the Flags One little lock flag per object does not sound like much, but when you consider that you can have 32 objects (including the player) in a scene plus the scene's lock flag, you are dealing with 33 flags per scene. This is more than enough to keep the player busy. In addition the open flag can often be used in a similar manner which can add another 33 flags. It is technically feasible to re-use an object's lock flag within the same local rule base since rules can expire before they conflict. People who design for this, though, deserve whatever consequences they get. Technically speaking, any object can be locked, but when applied to story situations, it would not make much sense if the player went around locking and unlocking or opening and closing everything in sight. (Which he or she could do, by the way, if the permission flags are not set. The default permission is therefore "NO" which requires you to specify which objects the player can lock or open.) Since most objects will have access to their flags denied to the player, their flags are available for use in your rules. 122 Figment User's Guide Story Design We use the Lock flag often in our rules. When the right conditions are met, we change the flag. Many other events are testing this flag, and when it changes, it triggers these events. You will see many rules in the Pre- and Post-command Rule Bases testing this flag. The executional functions, "Open" and "Close" are more powerful than the forms of these commands that the player uses. Notably, the Open executional function does not test the Lock flag. Hence objects can be opened or closed regardless of the status of their Lock flag. This makes the Open flag a free switch for you to use just like the Lock flag, for example for characters to indicate they will take an object if you give it. L. Reading Scrolls Scrolls just produce nice gibberish when they are read. You disable this by writing a pre-command rule that tests for the read function and disables it so you can substitute your message when the appropriate conditions are met. Since scrolls are defined by a sub-type attribute, objects can be things, features, and even characters and still qualify as scrolls. This means the player can read signs, inscriptions, monuments, documents etc. M. Strategic Weapons A strategic weapon is any weapon that functions at a distance. More specifically, it is an object whose sub-type attribute is set to read "Strategic". Their advantage should be obvious since they allow you to dispatch an opponent without risking a fight. This luxury does not come free however. You might be risking all since your shot is governed by a random process which could come up heavily against you. Strategic weapons come in two parts: the weapon itself and its ammunition. You must have both objects in order to shoot the weapon. Create both objects in the Stuff Editor and link the weapon to its ammunition. The limit attribute for the ammunition object determines how many times the weapon can be fired. It is decremented each time the weapon is fired. Actually, the ammunition is contrived to be an ammunition holder, for example: 123 Story Design Figment User's Guide Weapon Ammunition Holder gun clip, magazine, or chamber bow quiver phaser battery pack or power cell When the ammunition runs out, Figment reports, "Your <ammunition holder> is empty." The type attribute for strategics and ammunition should be "Thing". The sub-type attribute should be "Strategic" for the weapon and "Goody" for the ammunition holder. The player's skill largely determines the outcome which means that the lowest two skill levels should not use strategics. The best a Novice can do is avoid a self-inflicted injury. An Amateur can do better but cannot succeed in killing an opponent so there is little reason to try. The next three classes have a low, medium and high chance of success respectively. Strategics are a high risk weapon. Any skill level can still score so lowly with a strategic weapon that he or she dies of a self-inflicted wound. When the player scores high, however, the opponent is quickly dispatched. It must be said that some Wizards are better than other Wizards since it is an unlimited class, you just get more (or less) Wizardly. Therefore, when it comes to strategics, there can still be some surprisingly inept Wizards out there (You know who you are). Figment has some generic result messages for strategics that it will use, but you can write your own, more specific messages in a pre-command rule. Figment will look for an active rule testing for the shoot function and defer to the messages therein. This rule must be a "While" rule. (This is very important. Otherwise it will switch itself off and be skipped.) It would look something like this: Switched: On Command: Enabled While { Player does shoot bow ...other conditions... } Then { No executional expressions } Message 5 Total Switched: OFF Current Msg: 1 1 <Disaster> 2 <Bad but surviving> 3 <Still missed> 4 <Wounded opponent> 5 <Successful hit> This special rule in no way prohibits you from writing other pre- 124 Figment User's Guide Story Design command rules that will prevent the player from shooting, but those rules should appear after this special rule in the sequence (curious, but true). Figment will take the first "shoot" rule that it finds when it wants messages. Figment weights the results of the random number generator according to the Player's skill and grids the results on a scale of 1 to 5 with 1 being disastrous. It then reports the nth. message from your rule or its generic message list. A result of one is disastrous. The player's health is set to zero. This will kill the player, but it is subject to the aforementioned escape clause (see "Conflicts" above) so the player might survive severely wounded. Results of two and three are simply misses and only cost a move and the ammunition. A result of four results in wounding the opponent. The opposing object's health is decremented by the amount of the ammunition's strength. Remember to specify the health for the opposing object, otherwise this score will be equivalent to a successful hit regardless of the ammunition's strength. Consider also the effect of negative attributes for the ammunition's strength; the opponent would get healthier the more it was "wounded": "Ooh. Now you've made him very, very mad." Five is a successful hit. The opponent object will be stripped of its possessions and removed from the scene. The player's score will be incremented one point. You can write a post- command rule that tests for the absence of the opponent to deliver whooping congratulations and further increment the Player's score if you like. If your story line hinges around the opponent's corpse you may rename the late lamented object and reintroduce it with this same rule. Although you do want to specify your ammunition's strength, there is no need to specify strength or magic attributes for the strategic weapon itself. N. Food As mentioned under parameter editing, you can control Figment's behavior regarding food. Depending on your settings, your player may be satisfied for days between rations or they may be forced into a feeding frenzy. You also set the food value for the food item by setting the 125 Story Design Figment User's Guide object's limit attribute up to its maximum (32). Thus some foods may satisfy your craving while others are empty. (Didn't your mother tell you this?) The player's maximum gain from a food item is limited by his or her skill at the time the item is consumed so novices should conserve their rations while newly- anointed wizards might want to reward themselves with a pause for refreshment. You may also fortify your food with Strength, Magic and Health attributes since these will be added to the Player's when the food is consumed. Negative attributes are allowed here as with potions. Guard your food. Figment can be a bit piggish at times. Bon appetit. O. Characters as Containers Ordinarily, the player cannot tell when a character has an object, but if you set the character's sub-type attribute to "Container", Figment will report the container-character's contents when the character's Open flag is set to "Open". You can then write rules that manipulate the flag and hence display or not display the character's possessions at your whim. P. Rules and Changing Scenes From the nature of rule base processing as it was defined, you should understand how the rule bases perform when changing scenes. The last rule base to be processed when exiting a scene will be that scene's Pre-command Rule Base. The change-scene command will execute and the Post-command rules for the new scene will be processed. If you write rules fashioned as "If" rules and place them in the new scene's Post-command rule base, they can fire when the player arrives in the scene. These rules then serve to initialize the scene. Of course, these rules only function one time since "If" rules expire so the effect is lost when players repeatedly enter the same scene. Q. User-definable Command Parser The user-definable command parser allows virtually any command in play mode to trigger pre-command rules. The executable function, "say_cmnd" parses the command line 126 Figment User's Guide Story Design according to a specification given in the first message of a pre- command rule. It looks like this: If { Player does say_cmnd } Then { add_to Consulting Room Johnson copy msg to Player's view of Watson's Long Desc. change_score 1 } Message 2 Total Switched: OFF Current Msg: 2 1. (send or show)(him or Johnson)(in or up) or thank you mrs hudson 2. Watson prepares to take notes. The first message of the rule is a specification for acceptable words or phrases on a command line. The remaining messages are available for other uses. Let's see how the specification works. Imagine the situation: Your faithful housekeeper Mrs. Hudson announces your visitor. "There's a Mr. Johnson to see you, Mr. Holmes." Your reply might be: >show him in please or >send him up or >thank you mrs hudson The specification in the pre-command rule reads: (send or show)(him or Johnson)(in or up) or thank you mrs hudson The parentheses "()" serve to "AND" phrases while the keyword " or " serves as the boolean "OR" operator. This example specifies several acceptable combinations of words and/or phrases which we can group as follows: send him in show Johnson up It also allows the phrase: thank you Mrs Hudson This is something like choosing from a Chinese menu. Choose one from column A, one from column B, etc. According to this example, you must choose one from each column, because the 127 Story Design Figment User's Guide parentheses indicate they have all been anded together. This yields a number of legal statements that the player might give: send him in send Johnson in send him up send Johnson up show him in show Johnson in show him up show Johnson up thank you Mrs Hudson Of course if the player gives extra words, Figment will ignore them: >send him in please Mrs Hudson The player must give the full phrase in order to trigger the rule: >thank you is not enough unless you modify the specification to allow it: (send or show)(him or Johnson)(in or up) or thank you mrs hudson or thank you Another legitimate specification to achieve the same end is: (send or show)(him or Johnson)(in or up) or (thank you) (mrs hudson or ) A rule like this can be placed in any pre-command rule base either global or local. Presumably most will be local. The user-definable parser is deliberately tolerant. It will accept the legal phrases in any order. All that is required is to give the requisite number of phrases. The specification: (send or show)(him or Johnson)(in or up) or thank you mrs hudson will accept "him in send", but not "Mrs Hudson thank you" while the specification: (send or show)(him or Johnson)(in or up) or (thank you) (mrs hudson or) will accept "Mrs Hudson thank you". 128 Figment User's Guide Story Design The user-definable command parser can be negated. This has the effect of firing the rule until the player gives the desired command. For example: While { Player does not say_cmnd Consulting Room is linked to Mrs. Hudson } Then { No Executional Expressions. } Message 2 Total Switched: ON Current Msg: 2 1. (send or show)(him or Johnson)(in or up) or thank you mrs hudson 2. Mrs. Hudson discreetly clears her throat. The negated rule will fire until the player gives the specified command. You may wish to write negated command rules as "If" or "For" rules instead of "While" rules so that they can switch off after a few tries. Otherwise, they can be very frustrating. The user-parser has the third highest precedence after the system-level commands (restart, save, toggle, etc.) and the synonym processing so that you can use any word or phrase even if it is similar to Figment's built-in functions. Phrases like "take off" and "drop dead" can be used without triggering error messages: "There's no off here" or "You don't have a dead". Negated user-defined commands will not interfere with system level commands, because they have lower precedence. Note that punctuation must be avoided. Punctuation has special meaning to the command parser. The comma (,) means make a series operation as in "take bat, ball, glove". Similarly, the period (.) means end the command or separate commands. If the player gives the command: Thank you, Mrs. Hudson. Figment will interpret this as: Thank you ;"I don't understand the command `Thank'". Thank Mrs ;"I don't understand the command `Thank'". Hudson ;"I don't understand the command `Hudson'". The player must simply ignore punctuation except where it is used to signal series operation or command termination. Upper/lower case distinctions are of course ignored. There are words that will defeat your desired statement. You will want to exclude any statement that uses them. For example, the statement "send him in" would be defeated if the player used 129 Story Design Figment User's Guide "do not" as in "do not send him in" or "don't". The phrase "Thank you Mrs Hudson" would be defeated if the player said "No thank you Mrs Hudson". You want to specify these negative words, and you can do that by enclosing them in square brackets "[]" as follows: [do not or dont](send or show)(him or Johnson)(in or up) o r [no](thank you)(mrs hudson or ) The square brackets can be specified in any order. The following example is equivalent to the previous example: (send or show)(him or Johnson)(in or up)[do not or dont] or (thank you)(mrs hudson or )[no] Note that the contraction "don't" was written as "dont" and that the abbreviation "Mrs." was written as "mrs". Punctuation should not be included in the specification message, but upper/lower case distinctions do not matter. R. The Actor in Rules You can use the term "Actor" in your expressions wherever you might use a character. When you use the Actor, you are testing for "whomever might be speaking" as opposed to the Player which refers specifically to the object reserved for the user. Using the Actor in your conditional expressions has the advantage of flexibility since it is a more general term than "Player". This asset turns into a liability when you use it in executional expressions. It can produce chaos, because function destinations will be determined at run-time. There is no telling where the following message might end up although it is a correct construction: copy msg to Actor's view of Actor's Long Desc. Consider using the Actor instead of the Player when writing rules designed to contain the story to a particular scene until the user has resolved some task. If you do not test for the Actor, the user can change to another character and slip through to another scene and change back. A pre-command rule to prevent this might look like this: Scene: X Rule: 1 of n Switched: ON Disabled If { Actor does go Anywhere <scene name> is locked 130 Figment User's Guide Story Design } Then { No Executionals } Message 1 Total Switched: ON Current Message: 1 1. Sorry. You can't go yet. S. The '@'-Words Special system names and words can be incorporated into your text using special names within your text string. These special names are indicated by the at-symbol (@). The names must be spelled exactly as you see them here, including the capital letters. Whenever your text is used, Figment substitutes the appropriate text for the special name. Hence these special names function like text variables within your text. The words are: @Actor - Substitutes the current actor's name. @Player - Substitutes the current Player's name. Typically this yields the User's first name, but during development and testing of your story, it would be the generic text "Player". @Scene - Substitutes the current scene name. @It - Substitutes the last object name used in the command line. @Them - Substitutes the last series of object names used in the command line. @Full_name - Substitutes the user's full name. This is the preferred form when you want the full name since it avoids problems with titles, middle names, four names, reversed names, etc. @Full_name is loaded when "@Get_User" is inserted in the title message. If "@Get_User" is omitted from the title message, "@Full_name" is empty. @User[n] - where n = 0 through 2. Substitutes the User's first, middle or last name. User[0] is reliably the user's first name. User[1] is the middle name and is empty when less than three names are entered. User[2] is the second name when two names are entered, otherwise it is the third name. People with four names suffer. Titles such as "Sr., Jr., II, and III" are lost. Many cultures place the family name first and the individual's name last. There is no support for this. @User is loaded by @Get_User during title message processing. 131 Story Design Figment User's Guide @Command - Substitutes the current command sentence. You can give commands consisting of several sentences, but they are processed one sentence at a time so this returns the current sentence. @Words[n] - where n = 0 to maximum words in command line. Probably Words[0] is most useful since it is typically the verb. @Msg: n 132 Figment User's Guide Story Design Index + 37, 39, 51, 63 Conflicts @-Words 131 Conclusions 117 @Actor 131 design notes 116 @Command 132 Containers 7, 14, 22, 85, @Full_name 95, 131 119 @Get_User 95 link limit 119 @It 131 reporting contents of 41 @Player 131 Copy_Msg_To 85 @Scene 131 Cursor Control Keys 35 @Them 131 Cut 32, 36, 64 @User[n] 131 Expressions 72 @Words[n] 132 rules 63, 64 Actor Test Messages 73 during playback 11 Text 33 in rules 130 Data Set Files 108, 111 viewpoints 45 Debugging Tips 112 Advance 35 Delete 37, 63 Alphabetizing objects 40 Player object 40 Alt-F7 33, 37, 64, 72, 73 rules 63 Armor 41 with objects 39 Articles Directions in commands 9 during play 19 Assign_User_Type 84 Display Attributes switch 5 as arguments 70 Does_Action 77 editing operations 41 Does_Fit_Profile 78 failure to specify 113 Does_Have_Attribute 78 in scenes 49 Drink 14, 121 negative 118 Drop 15 with food 126 Eat 15 with potions 121 Editing Operations Change User-Attribute summary of 35 executional function 84 Error Messages change_health 115, 116 in editor 32 change_score 114 Examination Message 44, 115 Characters victory message 117 as containers 126 Examine 15 Charm 14 message design 115 CHKDSK 17 Executional Close 14, 85 clause 57 Comma Operator Executional Function in commands 9 Reference 84 Command Parser Expression 67 User-definable 126 editing 67 Command Reference 14 modifier 69, 75 Command Window 7 negation 68, 69 Conditional clause 57 F1 - Enter Editor 15, 34 types of 57 also exit from editor 36 133 Story Design Figment User's Guide F10 - DOS Shell 17, 37 Insert 32, 37, 64 in editor 35 Interrupt F2 36 log files 23 read a file 35 Inventory F3 changes w/actor 11 write a file 35, 36 DOS switch 5 F4 - Listing 36 Is_dead 78 objects 38 Is_linked_to 79 rule bases 66 Is_locked 80 F5 - Alphabetize Objects 36 Is_open 80 F6 9, 74 Is_type 81 F6 - Text Editor 36 Is_wizard 81 F7 32, 33, 36, 64, 72, 73 it 10 F9 - Step a log file 16 Kill 88 Figglu 3 Labels 47 Fight 17, 117 user types 43 Figlet 1 Limit File ammunition 123 input/output 35 editing 42 management 105 food value 126 naming convention 105 Link_to 88 Find 18 Links Flags 41, 42, 49 design notes 118 Food 42, 115, 118 editing operations 48 design notes 125 in scenes 49 limited by skill 114, 126 type labels 98 parameter editing 96 Listing sub-type attribute 41 objects 38 FOR 57, 61, 86 rule bases 66 Full-Screen Text Editor Lock 21, 58, 89 description of 104 editing 123 Give 18 Log 8, 21, 120 Global Rule Bases 65 play a log file 23 Go 19, 20, 70, 75, 87 step a log file 16 Go_to_Map_Block 86 Logic Programming 54 Goody Magic 116 sub-type attribute 41 editing 41 Have_Attribute 78 Message Health 17, 114 editing 73 design notes 115 pointer 61, 83, 87, 89 editing 41 Method of Editing 30 recovery 18 Move count 19, 24 Hex 20, 117 Msg_to_name 89 Hit 20 Negating rules 76 Home key 37, 68, 69 Negative Attributes IF 57 in conflicts 118 delayed execution 62 Objects Inc_moves 87 creating them 39 Inc_msg 87 definition of 38 Inc_score 85 deleting 39, 111 134 Figment User's Guide Story Design names 38 entry scene 52 User Types 43 objects 38 On_skill 89, 115 rules and changing 126 Open 22, 41, 49, 80, 90 Screen Display 6 Page-Down 35 Scrolling 30, 35 Parameter Scrolls 41, 123 editing 94 Series 9 Paste 32, 33, 64 Shift-F2 Pause 22 read save file 36 Period Operator Shift-F3 in commands 9 write save file 36 Play 23 Shift-F4 - Write Full Listing Player Map 92 36 Player Object 40 Shift-F7 33 Potions Shoot 26 design notes 121 Size 41, 122 Pre-Command Skill explanation of 74 design notes 114 Presentation Environment 4 is_wizard 81 Probable Event 81 levels 114 Profiles 99 on-skill 89 Pronouns 71 when shooting 26 Put 23 Standard Messages 101 Quit 24 Starting Random Number Generator existing story 4 controlling 120 new story 4, 106 Read 24 Status Remove_User_Type 90 editing 96 Restart 24, 109 Indicator 6 Restore 23, 24, 109 switch 5 Rules story adding/deleting 63 restarting 24, 25 changing scenes via 126 story editor 28 copying 63 story elements 34 current message 60 Story Design 114 definition of 57 Story Editor 28 editing 62 Story Map 19, 86, 93 expression editing 67 Complex maps 52 negating 76 editing 50 re-ordering 63 path 51 Save 17, 21, 23-25, 36, restricts scene change 65 105, 106, 108 Simple Maps 51 Say_cmnd 82 Strategic Weapons 123 Scene Description 49, 60 Strength 17, 116 highlights changes 6 design notes 116 with Actor change 11 editing 41 Scene Editor 49 Stuff 37 Scene-change 50 names 38 Scenes objects 38 changing in editor 65 Stuff Editor 37 135 Story Design Figment User's Guide Sub-type attribute 41 Synonym 93 Syntax explanation of symbols 14 Take 26 Take_from 90 Text changing it 31 erasing 31 length of 31 Text editor 31, 37 for commands 9 invoking 104 key definition summary 104 them 10 Toggle 6, 26 Toggle_lock 90 Toggle_open 90 Top Level Editor description of 34 file i/o 109 Type attribute 41, 50 Unlock 26, 91 User Types 43 defining labels 97 User-Definable Attributes defining labels 98 editing 46 User-definable Command Parser 126 Viewpoints editing 45 Wager 17 Wait 27 Weapon 41 Weight 41, 121 Weight factors in profiles 100 WHILE 57 136